You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@shenyu.apache.org by xi...@apache.org on 2022/01/04 03:04:24 UTC
[incubator-shenyu-website] branch main updated: Add shenyu-agent document (#423)
This is an automated email from the ASF dual-hosted git repository.
xiaoyu pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-shenyu-website.git
The following commit(s) were added to refs/heads/main by this push:
new c30d0eb Add shenyu-agent document (#423)
c30d0eb is described below
commit c30d0eba54805b65f64fdfbfd2a240ebb9eb5a19
Author: Kunshuai Zhu <jo...@gmail.com>
AuthorDate: Tue Jan 4 11:04:16 2022 +0800
Add shenyu-agent document (#423)
---
docs/user-guide/observability.md | 117 +++++++++++++++++++++
.../current/user-guide/observability.md | 117 +++++++++++++++++++++
2 files changed, 234 insertions(+)
diff --git a/docs/user-guide/observability.md b/docs/user-guide/observability.md
new file mode 100644
index 0000000..7e74f50
--- /dev/null
+++ b/docs/user-guide/observability.md
@@ -0,0 +1,117 @@
+---
+title: Observability
+keywords: ["Observability"]
+description: Observability access
+---
+
+This article introduces how to connect the `Apache ShenYu` gateway to the observability system.
+
+`Apache ShenYu` uses `java agent` and `bytecode enhancement` technology to achieve seamless embedding, so that users can access third-party observability systems without introducing dependencies, and obtain Traces, Metrics and Logging.
+
+## Download and compile the code
+
+- Download code
+
+```shell
+> git clone https://github.com/apache/incubator-shenyu.git
+```
+
+- Use Maven to compile the code
+
+```shell
+> cd incubator-shenyu
+> mvn clean install -Dmaven.javadoc.skip=true -B -Drat.skip=true -Djacoco.skip=true -DskipITs -DskipTests
+```
+
+After the compilation is successful, you can see the compiled jar package and related configuration files of the `shenyu-agent` module in the `~/shenyu/shenyu-dist/shenyu-agent-dist/target/shenyu-agent` directory.
+
+```text
+.
+├── conf
+│ ├── logback.xml
+│ ├── shenyu-agent.yaml
+│ └── tracing-point.yaml
+├── plugins
+│ ├── shenyu-agent-plugin-tracing-common-2.4.2-SNAPSHOT.jar
+│ ├── shenyu-agent-plugin-tracing-jaeger-2.4.2-SNAPSHOT.jar
+│ ├── shenyu-agent-plugin-tracing-opentelemetry-2.4.2-SNAPSHOT.jar
+│ └── shenyu-agent-plugin-tracing-zipkin-2.4.2-SNAPSHOT.jar
+└── shenyu-agent.jar
+```
+
+## Edit configuration file
+
+```yaml
+appName: shenyu-agent
+supports:
+ tracing:
+ - jaeger
+# - opentelemetry
+ metrics:
+ -
+ logging:
+ -
+
+plugins:
+ tracing:
+ jaeger:
+ host: "localhost"
+ port: 5775
+ props:
+ SERVICE_NAME: "shenyu-agent"
+ JAEGER_SAMPLER_TYPE: "const"
+ JAEGER_SAMPLER_PARAM: "1"
+ opentelemetry:
+ props:
+ otel.traces.exporter: jaeger #zipkin #otlp
+ otel.resource.attributes: "service.name=shenyu-agent"
+ otel.exporter.jaeger.endpoint: "http://localhost:14250/api/traces"
+ metrics:
+ prometheus:
+ host: "localhost"
+ port: 8081
+ props:
+ logging:
+ elasticSearch:
+ host: "localhost"
+ port: 8082
+ props:
+ kafka:
+ host: "localhost"
+ port: 8082
+ props:
+```
+
+- Select the plugin to be used in `supports`
+- Configure the parameters of the plug-in in `plugins`. The specific usage of each plug-in props parameter is shown in the following tables:
+
+#### jaeger
+
+| Name | Type | Default | Description |
+| :------------------- | :----: | :----------- | :-------------------------------------- |
+| SERVICE_NAME | String | shenyu-agent | The name displayed in the traces system |
+| JAEGER_SAMPLER_TYPE | String | const | Jaeger sample rate type |
+| JAEGER_SAMPLER_PARAM | String | 1 | Jaeger sample rate parameters |
+
+#### opentelemetry
+
+| Name | Type | Default | Description |
+| :----------------------- | :----: | :------------------------ | :----------------------------------------------------------- |
+| otel.traces.exporter | String | jaeger | Traces exporter type, if not filled in, the default is otlp |
+| otel.resource.attributes | String | service.name=shenyu-agent | otel resource attributes, if you fill in more than one, they can be separated by commas |
+
+The SDK used by the opentelemetry plugin is initialized based on `opentelemetry-sdk-extension-autoconfigure`. For more usage, please refer to [OpenTelemetry SDK AutoConfiguration Instructions](https://github.com/open-telemetry/opentelemetry-java/tree/v1.9.1/sdk-extensions/autoconfigure#opentelemetry-sdk-autoconfigure)
+
+## For use
+
+In the startup script to start the `Apache ShenYu` gateway, add the -javaagent parameter when running the jar package at the end, namely:
+
+```shell
+nohup java ${JAVA_OPTS}\
+-javaagent:${SHENYU_AGENT_PATH}/shenyu-agent.jar\
+-classpath ${CLASS_PATH} ${MAIN_CLASS} >> ${LOG_FILES} 2>&1 &
+```
+
+Where `${SHENYU_AGENT_PATH}` is the path of the `shenyu-agent` directory
+
+> Developers can add the `-javaagent` parameter to the JVM parameter of the IDE startup configuration
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/observability.md b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/observability.md
new file mode 100644
index 0000000..3f9faf7
--- /dev/null
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/observability.md
@@ -0,0 +1,117 @@
+---
+title: 可观测性接入
+keywords: ["Observability"]
+description: Observability access
+---
+
+此篇文章是介绍如何将 `Apache ShenYu` 网关接入可观测性系统。
+
+`Apache ShenYu` 利用 `java agent` 和 `字节码增强` 技术实现了无痕埋点，使得用户无需引入依赖即可接入第三方可观测性系统，获取 Traces、Metrics 和 Logging 。
+
+## 下载并编译代码
+
+- 下载代码
+
+```shell
+> git clone https://github.com/apache/incubator-shenyu.git
+```
+
+- 使用Maven编译代码
+
+```shell
+> cd incubator-shenyu
+> mvn clean install -Dmaven.javadoc.skip=true -B -Drat.skip=true -Djacoco.skip=true -DskipITs -DskipTests
+```
+
+编译成功后，在 `~/shenyu/shenyu-dist/shenyu-agent-dist/target/shenyu-agent` 目录下，可以看见 `shenyu-agent` 模块编译后的jar包和相关配置文件。
+
+```text
+.
+├── conf
+│ ├── logback.xml
+│ ├── shenyu-agent.yaml
+│ └── tracing-point.yaml
+├── plugins
+│ ├── shenyu-agent-plugin-tracing-common-2.4.2-SNAPSHOT.jar
+│ ├── shenyu-agent-plugin-tracing-jaeger-2.4.2-SNAPSHOT.jar
+│ ├── shenyu-agent-plugin-tracing-opentelemetry-2.4.2-SNAPSHOT.jar
+│ └── shenyu-agent-plugin-tracing-zipkin-2.4.2-SNAPSHOT.jar
+└── shenyu-agent.jar
+```
+
+## 编辑配置文件
+
+```yaml
+appName: shenyu-agent
+supports:
+ tracing:
+ - jaeger
+# - opentelemetry
+ metrics:
+ -
+ logging:
+ -
+
+plugins:
+ tracing:
+ jaeger:
+ host: "localhost"
+ port: 5775
+ props:
+ SERVICE_NAME: "shenyu-agent"
+ JAEGER_SAMPLER_TYPE: "const"
+ JAEGER_SAMPLER_PARAM: "1"
+ opentelemetry:
+ props:
+ otel.traces.exporter: jaeger #zipkin #otlp
+ otel.resource.attributes: "service.name=shenyu-agent"
+ otel.exporter.jaeger.endpoint: "http://localhost:14250/api/traces"
+ metrics:
+ prometheus:
+ host: "localhost"
+ port: 8081
+ props:
+ logging:
+ elasticSearch:
+ host: "localhost"
+ port: 8082
+ props:
+ kafka:
+ host: "localhost"
+ port: 8082
+ props:
+```
+
+- 在 supports 中选择要使用的插件
+- 在 plugins 中配置插件的参数，其中各插件props参数的具体使用见下面几个表格：
+
+##### jaeger
+
+| 名称 | 类型 | 默认值 | 说明 |
+| :------------------- | :----: | :----------- | :----------------------- |
+| SERVICE_NAME | String | shenyu-agent | 在traces系统中显示的名称 |
+| JAEGER_SAMPLER_TYPE | String | const | Jaeger 采样率类型 |
+| JAEGER_SAMPLER_PARAM | String | 1 | Jaeger 采样率参数 |
+
+##### opentelemetry
+
+| 名称 | 类型 | 默认值 | 说明 |
+| :----------------------- | :----: | :------------------------ | :------------------------------------- |
+| otel.traces.exporter | String | jaeger | traces导出器类型，若不填默认是otlp |
+| otel.resource.attributes | String | service.name=shenyu-agent | otel资源属性，若填写多个，可用逗号分隔 |
+
+opentelemetry 插件使用的sdk基于 `opentelemetry-sdk-extension-autoconfigure` 初始化，更多使用请参考 [OpenTelemetry SDK自动配置说明](https://github.com/open-telemetry/opentelemetry-java/tree/v1.9.1/sdk-extensions/autoconfigure#opentelemetry-sdk-autoconfigure)
+
+## 使用
+
+在启动 `Apache ShenYu` 网关的启动脚本中，最后运行jar包时加上-javaagent参数即可，即：
+
+```shell
+nohup java ${JAVA_OPTS}\
+-javaagent:${SHENYU_AGENT_PATH}/shenyu-agent.jar\
+-classpath ${CLASS_PATH} ${MAIN_CLASS} >> ${LOG_FILES} 2>&1 &
+```
+
+其中 `${SHENYU_AGENT_PATH}` 为 `shenyu-agent` 目录的路径
+
+> 开发者可将-javaagent参数添加到IDE启动配置的JVM参数中