You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@shenyu.apache.org by jo...@apache.org on 2022/01/04 09:22:16 UTC
[incubator-shenyu-website] branch main updated: add shenyu agent doc (#426)
This is an automated email from the ASF dual-hosted git repository.
jooks 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 b48631f add shenyu agent doc (#426)
b48631f is described below
commit b48631f35ce63556994e8578fc13e8d12455f734
Author: xiaoyu <xi...@apache.org>
AuthorDate: Tue Jan 4 17:22:10 2022 +0800
add shenyu agent doc (#426)
* add shenyu agent doc
* add shenyu agent doc
---
docs/user-guide/observability/_category_.json | 4 +
docs/user-guide/observability/observability.md | 99 ++++++++++++++++++++++
.../{observability.md => observability/tracing.md} | 76 ++++-------------
.../user-guide/observability/_category_.json | 4 +
.../user-guide/observability/observability.md | 99 ++++++++++++++++++++++
.../{observability.md => observability/tracing.md} | 80 +++++------------
6 files changed, 243 insertions(+), 119 deletions(-)
diff --git a/docs/user-guide/observability/_category_.json b/docs/user-guide/observability/_category_.json
new file mode 100644
index 0000000..8a01ee0
--- /dev/null
+++ b/docs/user-guide/observability/_category_.json
@@ -0,0 +1,4 @@
+{
+ "label": "Observability",
+ "position": 3
+}
diff --git a/docs/user-guide/observability/observability.md b/docs/user-guide/observability/observability.md
new file mode 100644
index 0000000..048c832
--- /dev/null
+++ b/docs/user-guide/observability/observability.md
@@ -0,0 +1,99 @@
+---
+title: Observability
+keywords: ["Observability"]
+description: Observability access
+---
+
+This article introduces the `Apache ShenYu Agent` module.
+
+## Java agent
+
+`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.
+
+## Tracing
+
+Link tracking, call chain data is collected via probes and third party systems (Jaeger, Zipkin) to pull the data and then display it.
+
+## Metrics
+
+System statistics metrics, collected by probes, are written to third-party timing databases such as prometheus and then displayed.
+
+## Logging
+
+Take the shenyu gateway log information, write it to elasticSearch (or send it to the messaging middleware), and display it.
+
+## 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-xxx.jar
+└── shenyu-agent.jar
+```
+
+## shenyu-agent.yaml
+
+```yaml
+appName: shenyu-agent
+supports:
+ tracing:
+ - pluginName
+ metrics:
+ - pluginName
+ logging:
+ - pluginName
+
+plugins:
+ tracing:
+ pluginName:
+ host:
+ port:
+ props:
+ metrics:
+ pluginName:
+ host:
+ port:
+ props:
+ logging:
+ pluginName:
+ host:
+ port:
+ 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:
+
+
+## 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/docs/user-guide/observability.md b/docs/user-guide/observability/tracing.md
similarity index 58%
rename from docs/user-guide/observability.md
rename to docs/user-guide/observability/tracing.md
index 7e74f50..81c6e54 100644
--- a/docs/user-guide/observability.md
+++ b/docs/user-guide/observability/tracing.md
@@ -1,29 +1,14 @@
---
-title: Observability
-keywords: ["Observability"]
-description: Observability access
+title: Tracing
+keywords: ["Tracing"]
+description: Tracing access
---
-This article introduces how to connect the `Apache ShenYu` gateway to the observability system.
+This article introduces how to use the `Apache ShenYu Agent Tracing`.
`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.
+## Catalog Structure
```text
.
@@ -32,26 +17,23 @@ After the compilation is successful, you can see the compiled jar package and re
│ ├── 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-plugin-tracing-common-${latest.release.version}-SNAPSHOT.jar
+│ ├── shenyu-agent-plugin-tracing-jaeger-${latest.release.version}-SNAPSHOT.jar
+│ ├── shenyu-agent-plugin-tracing-opentelemetry-${latest.release.version}-SNAPSHOT.jar
+│ └── shenyu-agent-plugin-tracing-zipkin-${latest.release.version}-SNAPSHOT.jar
└── shenyu-agent.jar
```
-## Edit configuration file
+## Edit shenyu-agent.yaml
```yaml
appName: shenyu-agent
supports:
tracing:
- jaeger
-# - opentelemetry
- metrics:
- -
- logging:
- -
-
+ - opentelemetry
+ - zipkin
+
plugins:
tracing:
jaeger:
@@ -61,25 +43,15 @@ plugins:
SERVICE_NAME: "shenyu-agent"
JAEGER_SAMPLER_TYPE: "const"
JAEGER_SAMPLER_PARAM: "1"
+ zipkin:
+ host:
+ port:
+ props:
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`
@@ -102,16 +74,4 @@ plugins:
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
+#### zipkin
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/observability/_category_.json b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/observability/_category_.json
new file mode 100644
index 0000000..8a01ee0
--- /dev/null
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/observability/_category_.json
@@ -0,0 +1,4 @@
+{
+ "label": "Observability",
+ "position": 3
+}
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/observability/observability.md b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/observability/observability.md
new file mode 100644
index 0000000..7e3ed72
--- /dev/null
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/observability/observability.md
@@ -0,0 +1,99 @@
+---
+title: 可观测性
+keywords: ["Observability"]
+description: Observability
+---
+
+此篇文章是介绍 `Apache ShenYu Agent` 模块。
+
+## Java agent
+
+`Apache ShenYu` 利用 `java agent` 和 `字节码增强` 技术实现了无痕埋点，使得用户无需引入依赖即可接入第三方可观测性系统，获取 Traces、Metrics 和 Logging 。
+
+## Tracing
+
+链路跟踪，通过探针收集调用链数据，第三方系统（Jaeger，Zipkin）来拉取数据后展示。
+
+## Metrics
+
+系统统计指标，通过探针收集，写入prometheus等第三方时序数据库，然后展示。
+
+## Logging
+
+将网关日志信息，写入elasticSearch（或者发送到消息中间件），然后展示。
+
+## 下载并编译代码
+
+- 下载代码
+
+```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-xxxxx.jar
+└── shenyu-agent.jar
+```
+
+## shenyu-agent.yaml 数据结构
+
+```yaml
+appName: shenyu-agent
+supports:
+ tracing:
+ - pluginName
+ metrics:
+ - pluginName
+ logging:
+ - pluginName
+
+plugins:
+ tracing:
+ pluginName:
+ host:
+ port:
+ props:
+ metrics:
+ pluginName:
+ host:
+ port:
+ props:
+ logging:
+ pluginName:
+ host:
+ port:
+ props:
+```
+
+- 在 supports 中选择要使用的插件
+- 在 plugins 中配置插件的参数，其中各插件props参数的具体使用见下面几个表格：
+
+
+## 使用
+
+在启动 `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参数中
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/tracing.md
similarity index 51%
rename from i18n/zh/docusaurus-plugin-content-docs/current/user-guide/observability.md
rename to i18n/zh/docusaurus-plugin-content-docs/current/user-guide/observability/tracing.md
index 3f9faf7..05de6d6 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/observability.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/observability/tracing.md
@@ -1,29 +1,12 @@
---
-title: 可观测性接入
-keywords: ["Observability"]
-description: Observability access
+title: 链路追踪接入
+keywords: ["Tracing"]
+description: Tracing access
---
-此篇文章是介绍如何将 `Apache ShenYu` 网关接入可观测性系统。
+此篇文章是介绍如何使用 `Apache ShenYu Agent`中的tracing功能。
-`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
.
@@ -32,26 +15,23 @@ description: Observability access
│ ├── 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-plugin-tracing-common-${latest.release.version}.jar
+│ ├── shenyu-agent-plugin-tracing-jaeger-${latest.release.version}-SNAPSHOT.jar
+│ ├── shenyu-agent-plugin-tracing-opentelemetry-${latest.release.version}-SNAPSHOT.jar
+│ └── shenyu-agent-plugin-tracing-zipkin-${latest.release.version}-SNAPSHOT.jar
└── shenyu-agent.jar
```
-## 编辑配置文件
+## 编辑配置文件(shenyu-agent.yaml)
```yaml
appName: shenyu-agent
supports:
tracing:
- jaeger
-# - opentelemetry
- metrics:
- -
- logging:
- -
-
+ - opentelemetry
+ - zipkin
+
plugins:
tracing:
jaeger:
@@ -61,28 +41,18 @@ plugins:
SERVICE_NAME: "shenyu-agent"
JAEGER_SAMPLER_TYPE: "const"
JAEGER_SAMPLER_PARAM: "1"
+ zipkin:
+ host:
+ port:
+ props:
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 中选择要使用的插件
+- 在 supports 中选择要使用的插件,如果不需要则去除
- 在 plugins 中配置插件的参数，其中各插件props参数的具体使用见下面几个表格：
##### jaeger
@@ -102,16 +72,4 @@ plugins:
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参数中
+##### Zipkin