[skywalking] branch doc created (now 97fdc8d)

[wu...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

wusheng pushed a change to branch doc
in repository https://gitbox.apache.org/repos/asf/skywalking.git.


      at 97fdc8d  Add Customization Config section for plugin development.

This branch includes the following new commits:

     new 97fdc8d  Add Customization Config section for plugin development.

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.

[skywalking] 01/01: Add Customization Config section for plugin development.

[wu...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

wusheng pushed a commit to branch doc
in repository https://gitbox.apache.org/repos/asf/skywalking.git

commit 97fdc8d6035fd8d39a3796fa61491badadcd01f7
Author: Wu Sheng <wu...@foxmail.com>
AuthorDate: Thu Aug 6 11:44:07 2020 +0800

    Add Customization Config section for plugin development.
---
 docs/en/guides/Java-Plugin-Development-Guide.md | 48 +++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/docs/en/guides/Java-Plugin-Development-Guide.md b/docs/en/guides/Java-Plugin-Development-Guide.md
index c4d589b..6054ff1 100644
--- a/docs/en/guides/Java-Plugin-Development-Guide.md
+++ b/docs/en/guides/Java-Plugin-Development-Guide.md
@@ -375,6 +375,54 @@ public class URLInstrumentation extends ClassEnhancePluginDefine {
 **NOTICE**, doing bootstrap instrumentation should only happen in necessary, but mostly it effect the JRE core(rt.jar),
 and could make very unexpected result or side effect.
 
+### Provide Customization Config for the Plugin
+The config could provide different behaviours based on the configurations. SkyWalking plugin mechanism provides the configuration
+injection and initialization system in the agent core.
+
+Every plugin could declare more or more classes to represent the config by using `@PluginConfig` annotation. The agent core
+could initialize this class' static field though System environments, System properties, and `agent.config` static file.
+
+The `#root()` method in the `@PluginConfig` annotation requires to declare the root class for the initialization process.
+Typically, SkyWalking prefers to use nested inner static classes for the hierarchy of the configuration. 
+Recommend using `Plugin`/`plugin-name`/`config-key` as the nested classes structure of the Config class.
+
+NOTE, because of the Java ClassLoader mechanism, the `@PluginConfig` annotation should be added on the real class used in the interceptor codes. 
+
+Such as, in the following example, `@PluginConfig(root = SpringMVCPluginConfig.class)` represents the initialization should 
+start with using `SpringMVCPluginConfig` as the root. Then the config key of the attribute `USE_QUALIFIED_NAME_AS_ENDPOINT_NAME`,
+should be `plugin.springmvc.use_qualified_name_as_endpoint_name`.
+```java
+public class SpringMVCPluginConfig {
+    public static class Plugin {
+        // NOTE, if move this annotation on the `Plugin` or `SpringMVCPluginConfig` class, it no longer has any effect. 
+        @PluginConfig(root = SpringMVCPluginConfig.class)
+        public static class SpringMVC {
+            /**
+             * If true, the fully qualified method name will be used as the endpoint name instead of the request URL,
+             * default is false.
+             */
+            public static boolean USE_QUALIFIED_NAME_AS_ENDPOINT_NAME = false;
+
+            /**
+             * This config item controls that whether the SpringMVC plugin should collect the parameters of the
+             * request.
+             */
+            public static boolean COLLECT_HTTP_PARAMS = false;
+        }
+
+        @PluginConfig(root = SpringMVCPluginConfig.class)
+        public static class Http {
+            /**
+             * When either {@link Plugin.SpringMVC#COLLECT_HTTP_PARAMS} is enabled, how many characters to keep and send
+             * to the OAP backend, use negative values to keep and send the complete parameters, NB. this config item is
+             * added for the sake of performance
+             */
+            public static int HTTP_PARAMS_LENGTH_THRESHOLD = 1024;
+        }
+    }
+}
+```
+
 ### Plugin Test Tool
 [Apache SkyWalking Agent Test Tool Suite](https://github.com/apache/skywalking-agent-test-tool)
 a tremendously useful test tools suite in a wide variety of languages of Agent. Includes mock collector and validator.