You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by ju...@apache.org on 2022/06/08 02:44:22 UTC
[apisix] branch master updated: docs: update skywalking Chinese doc (#7170)
This is an automated email from the ASF dual-hosted git repository.
juzhiyuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new a99eb64f2 docs: update skywalking Chinese doc (#7170)
a99eb64f2 is described below
commit a99eb64f23737a8796606f48b851e27be52a3e6e
Author: feihan <97...@users.noreply.github.com>
AuthorDate: Wed Jun 8 10:44:17 2022 +0800
docs: update skywalking Chinese doc (#7170)
---
docs/en/latest/plugins/skywalking.md | 3 +-
docs/zh/latest/plugins/skywalking.md | 259 +++++++++++++++++------------------
2 files changed, 126 insertions(+), 136 deletions(-)
diff --git a/docs/en/latest/plugins/skywalking.md b/docs/en/latest/plugins/skywalking.md
index 016f7cc29..44976d69b 100644
--- a/docs/en/latest/plugins/skywalking.md
+++ b/docs/en/latest/plugins/skywalking.md
@@ -4,8 +4,7 @@ keywords:
- APISIX
- Plugin
- SkyWalking
- - skywalking
-description: This document contains information about the Apache skywalking Plugin.
+description: This document will introduce how the API gateway Apache APISIX reports metrics to Apache SkyWalking (an open-source APM) with the skywalking plugin.
---
<!--
#
diff --git a/docs/zh/latest/plugins/skywalking.md b/docs/zh/latest/plugins/skywalking.md
index ffacde381..b8381e8cc 100644
--- a/docs/zh/latest/plugins/skywalking.md
+++ b/docs/zh/latest/plugins/skywalking.md
@@ -1,5 +1,10 @@
---
title: skywalking
+keywords:
+ - APISIX
+ - Plugin
+ - SkyWalking
+description: 本文将介绍 API 网关 Apache APISIX 如何通过 skywalking 插件将 metrics 上报到 Apache SkyWalking（一个开源的 APM）。
---
<!--
@@ -23,30 +28,94 @@ title: skywalking
## 描述
-[**SkyWalking**](https://github.com/apache/skywalking) 使用其原生的 Nginx LUA tracer 提供分布式追踪、拓扑分析以及服务和 URI 级别的 metrics 信息。
+`skywalking` 插件用于与 [Apache SkyWalking](https://github.com/apache/skywalking) 集成。
+
+SkyWalking 使用其原生的 NGINX Lua tracer 从服务和 URI 角度提供了分布式追踪、拓扑分析以及 metrics 。
服务端目前支持 HTTP 和 gRPC 两种协议，在 APISIX 中目前只支持 HTTP 协议。
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ------------ | ------ | ------ | -------- | ------------ | ----------------------------------------------------- |
-| sample_ratio | number | 必须 | 1 | [0.00001, 1] | 采样的比例 |
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+| ------------ | ------ | ------ | ------ | ------------ | ----------------------------------------------------- |
+| sample_ratio | number | 是 | 1 | [0.00001, 1] | 采样的比例。设置为 `1` 时，将对所有请求进行采样。 |
+
+### 如何设置 Endpoint
-## 如何启用
+你可以在配置文件（`./conf/config.yaml`）中配置以下属性：
-首先，你需要在 `config.yaml` 里面启用 SkyWalking 插件：
+| 名称 | 类型 | 默认值 | 描述 |
+| --------------------- | ------- | ------------------------ | ------------------------------------------------------------------ |
+| service_name | string | "APISIX" | SkyWalking 上报的服务名称。 |
+| service_instance_name | string | "APISIX Instance Name" | SkyWalking 上报的服务实例名。设置为 `$hostname` 时，将获取本机主机名。 |
+| endpoint_addr | string | "http://127.0.0.1:12800" | SkyWalking 的 HTTP endpoint 地址，例如：`http://127.0.0.1:12800`。 |
+| report_interval | integer | SkyWalking 客户端内置的值 | 上报间隔时间，单位为秒。 |
+以下是配置示例：
+
+```yaml title="./conf/config.yaml"
+plugin_attr:
+ skywalking:
+ service_name: APISIX
+ service_instance_name: "APISIX Instance Name"
+ endpoint_addr: http://127.0.0.1:12800
```
-# 加到 config.yaml
+
+### 上游服务示例代码
+
+```java title="Java with Spring Boot"
+package com.lenovo.ai.controller;
+
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+import javax.servlet.http.HttpServletRequest;
+
+/**
+ * @author cyxinda
+ * @create 2020-05-29 14:02
+ * @desc skywalking test controller
+ **/
+@RestController
+public class TestController {
+ @RequestMapping("/uid/{count}")
+ public String getUidList(@PathVariable("count") String countStr, HttpServletRequest request) {
+ System.out.println("counter:::::"+countStr);
+ return "OK";
+ }
+}
+
+```
+
+在启动服务前，需要配置 SkyWalking agent：
+
+```shell title="agent/config/agent.config"
+agent.service_name=yourservername
+collector.backend_service=10.110.149.175:11800
+```
+
+使用以下命令启动服务脚本：
+
+```shell
+nohup java -javaagent:/root/skywalking/app/agent/skywalking-agent.jar \
+-jar /root/skywalking/app/app.jar \
+--server.port=8089 \
+2>&1 > /root/skywalking/app/logs/nohup.log &
+```
+
+## 启用插件
+
+该插件默认是禁用状态，你需要将其添加到配置文件（`./conf/config.yaml`）中才可以启用它：
+
+```yaml title="./conf/config.yaml"
plugins:
- - ... # plugin you need
+ - ...
- skywalking
```
-然后重载 APISIX，这样会创建一个后台定时器，向 SkyWalking OAP 服务定期上报数据。
+配置完成后，重新加载 APISIX，此时 APISIX 会创建一个后台定时器，向 SkyWalking OAP 服务定期上报数据。
-下面是一个示例，在指定的 route 上开启了 SkyWalking 插件：
+以下示例展示了如何在指定路由中启用 `skywalking` 插件：
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -69,102 +138,72 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
}'
```
-你也可以通过 web 界面来完成上面的操作，先增加一个 route，然后在插件页面中添加 SkyWalking 插件：
-
-
+<!-- 你也可以通过 web 界面来完成上面的操作，先增加一个 route，然后在插件页面中添加 SkyWalking 插件：
-## 如何设置 Endpoint
-
-我们可以通过指定 `conf/config.yaml` 中的配置来指定 endpoint：
-
-| 名称 | 类型 | 默认值 | 描述 |
-| ------------ | ------ | -------- | ----------------------------------------------------- |
-| service_name | string | "APISIX" | SkyWalking 上报的 service 名称 |
-| service_instance_name | string | "APISIX Instance Name" | SkyWalking 上报的 service 实例名，如果期望直接获取本机主机名则设置为 `$hostname` |
-| endpoint_addr | string | "http://127.0.0.1:12800" | SkyWalking 的 HTTP endpoint 地址，例如：http://127.0.0.1:12800 |
-| report_interval | integer | 使用 SkyWalking 客户端内置的值 | 上报时间间隔，单位是秒 |
-
-配置示例：
-
-```yaml
-plugin_attr:
- skywalking:
- service_name: APISIX
- service_instance_name: "APISIX Instance Name"
- endpoint_addr: http://127.0.0.1:12800
-```
+ -->
## 测试插件
-### 运行 SkyWalking 实例
-
-#### 例子：
-
-1. 启动 SkyWalking OAP 服务：
- - SkyWalking 默认使用 H2 存储，可直接启动
-
- ```shell
- sudo docker run --name skywalking -d -p 1234:1234 -p 11800:11800 -p 12800:12800 --restart always apache/skywalking-oap-server:8.7.0-es6
- ```
+首先你可以通过 [Docker Compose](https://docs.docker.com/compose/install/) 启动 SkyWalking OAP 和 SkyWalking UI：
- - 也许你会更倾向于使用 Elasticsearch 存储
- 1. 则需要先安装 Elasticsearch:
+ - 在 usr/local 中创建 `skywalking.yaml` 文件。
- ```shell
- sudo docker run -d --name elasticsearch -p 9200:9200 -p 9300:9300 --restart always -e "discovery.type=single-node" elasticsearch:6.7.2
- ```
+ ```yaml
+ version: "3"
+ services:
+ oap:
+ image: apache/skywalking-oap-server:8.9.1
+ restart: always
+ ports:
+ - "12800:12800/tcp"
- 2.【可选】安装 ElasticSearch 管理界面 elasticsearch-hq
+ ui:
+ image: apache/skywalking-ui:8.9.1
+ restart: always
+ ports:
+ - "8080:8080/tcp"
+ environment:
+ SW_OAP_ADDRESS: http://oap:12800
+ ```
- ```shell
- sudo docker run -d --name elastic-hq -p 5000:5000 --restart always elastichq/elasticsearch-hq
- ```
+ - 使用以下命令启动上述创建的文件：
- 3. 启动 SkyWalking OAP 服务：
+ ```shell
+ docker-compose -f skywalking.yaml up -d
+ ```
- ```shell
- sudo docker run --name skywalking -d -p 1234:1234 -p 11800:11800 -p 12800:12800 --restart always --link elasticsearch:elasticsearch -e SW_STORAGE=elasticsearch -e SW_STORAGE_ES_CLUSTER_NODES=elasticsearch:9200 apache/skywalking-oap-server:8.7.0-es6
- ```
+ 完成上述操作后，就已经启动了 SkyWalking 以及 SkyWalking Web UI。你可以使用以下命令确认容器是否正常运行：
-2. SkyWalking Web UI：
- 1. 启动管理系统：
+ ```shell
+ docker ps
+ ```
- ```shell
- sudo docker run --name skywalking-ui -d -p 8080:8080 --link skywalking:skywalking -e SW_OAP_ADDRESS=skywalking:12800 --restart always apache/skywalking-ui
- ```
+接下来你可以通过以下命令访问 APISIX：
- 2. 打开 Web UI 页面
- 在浏览器里面输入 http://10.110.149.175:8080 如出现如下界面，则表示安装成功
-
- 
+```shell
+curl -v http://10.110.149.192:9080/uid/12
+```
-3. 测试示例：
- - 通过访问 APISIX，访问上游服务
+```
+HTTP/1.1 200 OK
+OK
+...
+```
- ```bash
- $ curl -v http://10.110.149.192:9080/uid/12
- HTTP/1.1 200 OK
- OK
- ...
- ```
+完成上述步骤后，打开浏览器，访问 SkyWalking 的 UI 页面，你可以看到如下服务拓扑图：
- - 打开浏览器，访问 SkyWalking 的 UI 页面：
+
- ```bash
- http://10.110.149.175:8080/
- ```
+并且可以看到服务追踪列表：
- 可以看到服务拓扑图\
- \
- 可以看到服务追踪列表\
- 
+
## 禁用插件
-当你想禁用一条路由/服务上的 SkyWalking 插件的时候，很简单，在插件的配置中把对应的 JSON 配置删除即可，无须重启服务，即刻生效：
+当你需要禁用 `skywalking` 插件时，可通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uris": [
@@ -181,58 +220,10 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335
}'
```
-现在就已经移除了 SkyWalking 插件了。其他插件的开启和移除也是同样的方法。
-
-如果你想完全禁用 SkyWalking 插件，比如停掉后台上报数据的定时器，需要在 `config.yaml` 里把插件注释掉：
+如果你想完全禁用 `skywalking` 插件，即停掉后台上报数据的定时器，就需要从配置文件（`./conf/config.yaml`）注释该插件：
-```yaml
+```yaml title="./conf/config.yaml"
plugins:
- - ... # plugin you need
+ - ...
#- skywalking
```
-
-然后重载 APISIX 即可。
-
-## 上游服务为 SpringBoot 的示例代码
-
-```java
-package com.lenovo.ai.controller;
-
-import org.springframework.web.bind.annotation.PathVariable;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
-import javax.servlet.http.HttpServletRequest;
-
-/**
- * @author cyxinda
- * @create 2020-05-29 14:02
- * @desc skywalking test controller
- **/
-@RestController
-public class TestController {
- @RequestMapping("/uid/{count}")
- public String getUidList(@PathVariable("count") String countStr, HttpServletRequest request) {
- System.out.println("counter:::::"+countStr);
- return "OK";
- }
-}
-
-```
-
-启动服务的时候，需要配置 SkyWalking agent。
-
-通过 `agent/config/agent.config` 修改配置
-
-```shell
-agent.service_name=yourservername
-collector.backend_service=10.110.149.175:11800
-```
-
-启动服务脚本：
-
-```shell
-nohup java -javaagent:/root/skywalking/app/agent/skywalking-agent.jar \
--jar /root/skywalking/app/app.jar \
---server.port=8089 \
-2>&1 > /root/skywalking/app/logs/nohup.log &
-```