update java agent guide (#268)

* update java agent guide Signed-off-by: CeerDecy <[email protected]> * polish: repair indentation and image url Signed-off-by: CeerDecy <[email protected]> --------- Signed-off-by: CeerDecy <[email protected]>
erda-project · Oct 25, 2024 · de6aea0 · de6aea0
1 parent 2e03306
commit de6aea0
Show file tree

Hide file tree

Showing 6 changed files with 281 additions and 2 deletions.
diff --git a/docs/2.4/manual/faq/faq.md b/docs/2.4/manual/faq/faq.md
@@ -281,4 +281,8 @@ burst 主要作用是做一个缓存，把当前不能处理的请求先缓存
 
 ### 第二个不精确限流的原因
 
-可以看到，到这里，tps 再一次不精确了。因为，请求达到的时间、爆发量等都会造成请求虽然没达到限制，但仍然被拒绝处理的情况（比如配置 burst=5, nginx 配置的是 10/s 的情况，如果每秒只有 10 个请求进入，但 10 个请求都是在每秒的第一个 100ms 内进入，那么实际最多能处理 6 个 请求，而另外 4 个则拒绝。因此看起来反而是限制为 6/s 而不是设置看起来的 10/s。
+可以看到，到这里，tps 再一次不精确了。因为，请求达到的时间、爆发量等都会造成请求虽然没达到限制，但仍然被拒绝处理的情况（比如配置 burst=5, nginx 配置的是 10/s 的情况，如果每秒只有 10 个请求进入，但 10 个请求都是在每秒的第一个 100ms 内进入，那么实际最多能处理 6 个 请求，而另外 4 个则拒绝。因此看起来反而是限制为 6/s 而不是设置看起来的 10/s。
+
+## 17. 配置的环境变量不生效？
+
+在Erda中配置的环境变量是存在优先级顺序的，可以参考[环境变量优先级](../dop/guides/deploy/config.md#优先级)进行配置
diff --git a/docs/2.4/manual/msp/guides/apm/java-agent-guide.md b/docs/2.4/manual/msp/guides/apm/java-agent-guide.md
@@ -15,6 +15,34 @@
 无侵入式开发可实现无感知接入 Agent。在 Erda 中，您只需通过 Pipeline 部署服务即可接入，无需其他操作。Pipeline 具体流程请参见 [基于 Git 源码部署](../../../dop/examples/deploy/deploy-from-git.md)。
 目前已支持 buildpack、buildpack-aliyun、java-build、java 等 action 的无缝构建。
 
+#### 关闭Agent
+
+Erda部署的应用默认会开启Java Agent，可以通过配置环境变量`TERMINUS_AGENT_ENABLE=false`来关闭。
+
+**Example: **
+
+注入应用级别的环境变量，可以在dice.yml中添加env
+
+```yaml
+services:
+  showcase-front:
+    envs:
+      TERMINUS_AGENT_ENABLE: false
+    health_check:
+      http:
+        port: 7079
+        path: /status
+        duration: 120
+
+addons:
+  zk:
+    plan: zookeeper:large
+```
+
+在应用中设置环境变量
+
+![img](http://terminus-paas.oss-cn-hangzhou.aliyuncs.com/paas-doc/2024/10/25/c0c18773-2f1a-4f77-b024-c5239eb10169.png)
+
 ### 插件
 
 #### 支持的插件列表
@@ -84,3 +112,64 @@ MSP_METHOD_INTERCEPT_POINTS = io.terminus.class1#method1,io.terminus.class2#meth
 ### 以下示例可拦截 io.terminus 包下的所有函数
 MSP_PACKAGE_INTERCEPT_POINTS = io.terminus
 ```
+
+#### 启用或关闭插件
+
+由于 java-agent 使用字节码注入等技术构建探针, 在插件更新时, 可能会遇到类名找不到等问题.
+
+此时可以先暂时关闭报错的插件
+
+```
+MSP_PLUGIN_{插件名称}_ENABLED=false
+```
+
+请使用表格中的环境变量, 替换上方的`{插件名称}`
+
+| 插件                | 对应环境变量名称       |
+| ------------------- | ---------------------- |
+| agent-sdk           | MONITORSDK             |
+| dubbo               | DUBBO                  |
+| dubbo-2.7.x         | DUBBO                  |
+| feign               | FEIGN                  |
+| trantor             | TRANTOR                |
+| jedis-2.x           | JEDIS                  |
+| redisson-3.x        | REDISSON               |
+| rocketmq-4.x        | ROCKETMQ               |
+| httpclient-4.x      | APACHE_HTTPCLIENT      |
+| http async client   | APACHE_HTTPASYNCCLIENT |
+| sharding-sphere-4.x | SHARDINGSPHERE         |
+| log4j2              | LOG4J2                 |
+| logback             | LOGBACK                |
+| logback-spring-boot | LOGBACK                |
+| mysql-5.x           | MYSQL                  |
+| mysql-8.x           | MYSQL                  |
+| okhttp 4.x          | OKHTTP                 |
+| lettuce-5.x         | LETTUCE                |
+| jetty-servlet       | JETTY                  |
+| tomcat-servlet      | TOMCAT                 |
+| resttemplate        | RESTTEMPLATE           |
+| concurrent-util-4.x | SPRING_CONCURRENTUTIL  |
+
+**Example: **
+
+注入应用级别的环境变量，可以在dice.yml中添加env
+
+```yaml
+services:
+  showcase-front:
+    envs:
+      MSP_PLUGIN_DUBBO_ENABLED: false
+    health_check:
+      http:
+        port: 7079
+        path: /status
+        duration: 120
+
+addons:
+  zk:
+    plan: zookeeper:large
+```
+
+在应用中设置环境变量
+
+![img](http://terminus-paas.oss-cn-hangzhou.aliyuncs.com/paas-doc/2024/10/25/ee6a868b-e69b-4636-894f-f251acbf9699.png)
diff --git a/docs/en/next/manual/faq/faq.md b/docs/en/next/manual/faq/faq.md
@@ -211,3 +211,7 @@ enter the ** cloud management platform > container resources > pods **, selects
 
 Click the record, you can see the container of the pipeline. You can enter the container console, and then debug in container.
 
+
+17. Environment Variables Not Taking Effect?
+
+Environment variables configured in Erda have a specific priority order. You can refer to [Environment Variable Priority]((../dop/guides/deploy/config.md#Priority) for configuration details.
diff --git a/docs/en/next/manual/msp/guides/apm/java-agent-guide.md b/docs/en/next/manual/msp/guides/apm/java-agent-guide.md
@@ -14,6 +14,34 @@ Generally, the entry point for Java is the main method, while the entry point fo
 ### Access Method
 Non-intrusive development allows agent access without perception. In Erda, you only need to deploy services via pipeline for access. For details, see [Deploy Based on Git Source Code](../../../dop/examples/deploy/deploy-from-git.md). Actions such as buildpack, buildpack-aliyun, java-build and java are supported now.
 
+#### Turning off the Java Agent
+
+The application deployed in Erda will have Java Agent enabled by default. You can disable it by setting the environment variable `TERMINUS_AGENT_ENABLE=false`.
+
+**Example:**
+
+To inject application-level environment variables, you can add them in the `dice.yml` file under the `env` section.
+
+```yaml
+services:
+  showcase-front:
+    envs:
+      TERMINUS_AGENT_ENABLE: false
+    health_check:
+      http:
+        port: 7079
+        path: /status
+        duration: 120
+
+addons:
+  zk:
+    plan: zookeeper:large
+```
+
+Set environment variables in the application.
+
+![image-20241024175306208](http://terminus-paas.oss-cn-hangzhou.aliyuncs.com/paas-doc/2024/10/24/e467ab6b-04c4-4e74-8b36-9e63a4e6ac73.png)
+
 ### Plugin
 
 #### Supported Plugins
@@ -83,3 +111,64 @@ If there are many classes under the package, using variables will increase the t
 ### The following example intercepts all functions under the io.terminus package
 MSP_PACKAGE_INTERCEPT_POINTS = io.terminus
 ```
+
+#### Enable or Disable Plugins
+
+Since the Java agent uses techniques such as bytecode injection to build probes, you may encounter issues like class not found errors when updating plugins.
+
+In such cases, you can temporarily disable the plugin causing the error:
+
+```
+MSP_PLUGIN_{PLUGIN_NAME}_ENABLED=false
+```
+
+Please use the environment variable from the table and replace `{PLUGIN_NAME}` with the relevant plugin name.
+
+| Plugins             | Env variables plugin name |
+| ------------------- | ------------------------- |
+| agent-sdk           | MONITORSDK                |
+| dubbo               | DUBBO                     |
+| dubbo-2.7.x         | DUBBO                     |
+| feign               | FEIGN                     |
+| trantor             | TRANTOR                   |
+| jedis-2.x           | JEDIS                     |
+| redisson-3.x        | REDISSON                  |
+| rocketmq-4.x        | ROCKETMQ                  |
+| httpclient-4.x      | APACHE_HTTPCLIENT         |
+| http async client   | APACHE_HTTPASYNCCLIENT    |
+| sharding-sphere-4.x | SHARDINGSPHERE            |
+| log4j2              | LOG4J2                    |
+| logback             | LOGBACK                   |
+| logback-spring-boot | LOGBACK                   |
+| mysql-5.x           | MYSQL                     |
+| mysql-8.x           | MYSQL                     |
+| okhttp 4.x          | OKHTTP                    |
+| lettuce-5.x         | LETTUCE                   |
+| jetty-servlet       | JETTY                     |
+| tomcat-servlet      | TOMCAT                    |
+| resttemplate        | RESTTEMPLATE              |
+| concurrent-util-4.x | SPRING_CONCURRENTUTIL     |
+
+**Example: **
+
+To inject application-level environment variables, you can add them in the `dice.yml` file under the `env` section.
+
+```yaml
+services:
+  showcase-front:
+    envs:
+      MSP_PLUGIN_DUBBO_ENABLED: false
+    health_check:
+      http:
+        port: 7079
+        path: /status
+        duration: 120
+
+addons:
+  zk:
+    plan: zookeeper:large
+```
+
+Set environment variables in the application.
+
+![img](http://terminus-paas.oss-cn-hangzhou.aliyuncs.com/paas-doc/2024/10/24/6815cae0-4561-4ae2-af34-900d63e61cbd.png)
diff --git a/docs/next/manual/faq/faq.md b/docs/next/manual/faq/faq.md
@@ -281,4 +281,8 @@ burst 主要作用是做一个缓存，把当前不能处理的请求先缓存
 
 ### 第二个不精确限流的原因
 
-可以看到，到这里，tps 再一次不精确了。因为，请求达到的时间、爆发量等都会造成请求虽然没达到限制，但仍然被拒绝处理的情况（比如配置 burst=5, nginx 配置的是 10/s 的情况，如果每秒只有 10 个请求进入，但 10 个请求都是在每秒的第一个 100ms 内进入，那么实际最多能处理 6 个 请求，而另外 4 个则拒绝。因此看起来反而是限制为 6/s 而不是设置看起来的 10/s。
+可以看到，到这里，tps 再一次不精确了。因为，请求达到的时间、爆发量等都会造成请求虽然没达到限制，但仍然被拒绝处理的情况（比如配置 burst=5, nginx 配置的是 10/s 的情况，如果每秒只有 10 个请求进入，但 10 个请求都是在每秒的第一个 100ms 内进入，那么实际最多能处理 6 个 请求，而另外 4 个则拒绝。因此看起来反而是限制为 6/s 而不是设置看起来的 10/s。
+
+## 17. 配置的环境变量不生效？
+
+在Erda中配置的环境变量是存在优先级顺序的，可以参考[环境变量优先级](../dop/guides/deploy/config.md#优先级)进行配置
diff --git a/docs/next/manual/msp/guides/apm/java-agent-guide.md b/docs/next/manual/msp/guides/apm/java-agent-guide.md
@@ -15,6 +15,34 @@
 无侵入式开发可实现无感知接入 Agent。在 Erda 中，您只需通过 Pipeline 部署服务即可接入，无需其他操作。Pipeline 具体流程请参见 [基于 Git 源码部署](../../../dop/examples/deploy/deploy-from-git.md)。
 目前已支持 buildpack、buildpack-aliyun、java-build、java 等 action 的无缝构建。
 
+#### 关闭Agent
+
+Erda部署的应用默认会开启Java Agent，可以通过配置环境变量`TERMINUS_AGENT_ENABLE=false`来关闭。
+
+**Example: **
+
+注入应用级别的环境变量，可以在dice.yml中添加env
+
+```yaml
+services:
+  showcase-front:
+    envs:
+      TERMINUS_AGENT_ENABLE: false
+    health_check:
+      http:
+        port: 7079
+        path: /status
+        duration: 120
+
+addons:
+  zk:
+    plan: zookeeper:large
+```
+
+在应用中设置环境变量
+
+![img](http://terminus-paas.oss-cn-hangzhou.aliyuncs.com/paas-doc/2024/10/25/c0c18773-2f1a-4f77-b024-c5239eb10169.png)
+
 ### 插件
 
 #### 支持的插件列表
@@ -84,3 +112,64 @@ MSP_METHOD_INTERCEPT_POINTS = io.terminus.class1#method1,io.terminus.class2#meth
 ### 以下示例可拦截 io.terminus 包下的所有函数
 MSP_PACKAGE_INTERCEPT_POINTS = io.terminus
 ```
+
+#### 启用或关闭插件
+
+由于 java-agent 使用字节码注入等技术构建探针, 在插件更新时, 可能会遇到类名找不到等问题.
+
+此时可以先暂时关闭报错的插件
+
+```
+MSP_PLUGIN_{插件名称}_ENABLED=false
+```
+
+请使用表格中的环境变量, 替换上方的`{插件名称}`
+
+| 插件                | 对应环境变量名称       |
+| ------------------- | ---------------------- |
+| agent-sdk           | MONITORSDK             |
+| dubbo               | DUBBO                  |
+| dubbo-2.7.x         | DUBBO                  |
+| feign               | FEIGN                  |
+| trantor             | TRANTOR                |
+| jedis-2.x           | JEDIS                  |
+| redisson-3.x        | REDISSON               |
+| rocketmq-4.x        | ROCKETMQ               |
+| httpclient-4.x      | APACHE_HTTPCLIENT      |
+| http async client   | APACHE_HTTPASYNCCLIENT |
+| sharding-sphere-4.x | SHARDINGSPHERE         |
+| log4j2              | LOG4J2                 |
+| logback             | LOGBACK                |
+| logback-spring-boot | LOGBACK                |
+| mysql-5.x           | MYSQL                  |
+| mysql-8.x           | MYSQL                  |
+| okhttp 4.x          | OKHTTP                 |
+| lettuce-5.x         | LETTUCE                |
+| jetty-servlet       | JETTY                  |
+| tomcat-servlet      | TOMCAT                 |
+| resttemplate        | RESTTEMPLATE           |
+| concurrent-util-4.x | SPRING_CONCURRENTUTIL  |
+
+**Example: **
+
+注入应用级别的环境变量，可以在dice.yml中添加env
+
+```yaml
+services:
+  showcase-front:
+    envs:
+      MSP_PLUGIN_DUBBO_ENABLED: false
+    health_check:
+      http:
+        port: 7079
+        path: /status
+        duration: 120
+
+addons:
+  zk:
+    plan: zookeeper:large
+```
+
+在应用中设置环境变量
+
+![img](http://terminus-paas.oss-cn-hangzhou.aliyuncs.com/paas-doc/2024/10/25/ee6a868b-e69b-4636-894f-f251acbf9699.png)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -211,3 +211,7 @@ enter the cloud management platform > container resources > pods , selects

		Click the record, you can see the container of the pipeline. You can enter the container console, and then debug in container.


		17. Environment Variables Not Taking Effect?

		Environment variables configured in Erda have a specific priority order. You can refer to [Environment Variable Priority]((../dop/guides/deploy/config.md#Priority) for configuration details.