[skywalking] branch master updated: Add Customization Config section for plugin development. (#5249)

[wu...@apache.org]

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

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


The following commit(s) were added to refs/heads/master by this push:
     new 6910ff3  Add Customization Config section for plugin development. (#5249)
6910ff3 is described below

commit 6910ff3d07f5d21f73153f1ef93e22794d17843e
Author: 吴晟 Wu Sheng <wu...@foxmail.com>
AuthorDate: Thu Aug 6 14:44:42 2020 +0800

    Add Customization Config section for plugin development. (#5249)
---
 apm-protocol/apm-network/src/main/proto         |  2 +-
 docs/en/guides/Java-Plugin-Development-Guide.md | 48 +++++++++++++++++++++++++
 2 files changed, 49 insertions(+), 1 deletion(-)

diff --git a/apm-protocol/apm-network/src/main/proto b/apm-protocol/apm-network/src/main/proto
index 87ed1f4..89381e1 160000
--- a/apm-protocol/apm-network/src/main/proto
+++ b/apm-protocol/apm-network/src/main/proto
@@ -1 +1 @@
-Subproject commit 87ed1f4e31b0517a7efff27d46a47829c7f533f9
+Subproject commit 89381e14f9c29c4ee240c5e55c66ab44381924ca
diff --git a/docs/en/guides/Java-Plugin-Development-Guide.md b/docs/en/guides/Java-Plugin-Development-Guide.md
index c4d589b..f5fa073 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 one 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.