From 224944de422df655a105a9aba6d082d6a133d43e Mon Sep 17 00:00:00 2001 From: traky Date: Wed, 5 Feb 2025 14:28:04 +0800 Subject: [PATCH] improve docs --- docs/en/latest/plugins/skywalking.md | 241 ++++++++++---------------- docs/zh/latest/plugins/skywalking.md | 242 ++++++++++----------------- 2 files changed, 181 insertions(+), 302 deletions(-) diff --git a/docs/en/latest/plugins/skywalking.md b/docs/en/latest/plugins/skywalking.md index e73ac9552eb0..05020c9ddae0 100644 --- a/docs/en/latest/plugins/skywalking.md +++ b/docs/en/latest/plugins/skywalking.md @@ -5,8 +5,9 @@ keywords: - API Gateway - Plugin - SkyWalking -description: This document will introduce how the API gateway Apache APISIX reports metrics to Apache SkyWalking (an open-source APM) with the skywalking plugin. +description: The skywalking Plugin supports the integrating with Apache SkyWalking for request tracing. --- + + + + + ## Description -The `skywalking` Plugin is used to integrate with [Apache SkyWalking](https://github.com/apache/skywalking). +The `skywalking` Plugin supports the integrating with [Apache SkyWalking](https://skywalking.apache.org) for request tracing. -SkyWalking uses its native Nginx Lua tracer to provide tracing, topology analysis, and metrics from both service and URI perspectives. +SkyWalking uses its native Nginx Lua tracer to provide tracing, topology analysis, and metrics from both service and URI perspectives. APISIX supports HTTP protocol to interact with the SkyWalking server. -APISIX supports HTTP protocol to interact with the SkyWalking server. +The server currently supports two protocols: HTTP and gRPC. In APISIX, only HTTP is currently supported. -## Attributes +## Static Configurations -| Name | Type | Required | Default | Valid values | Description | -|--------------|--------|----------|---------|--------------|----------------------------------------------------------------------------| -| sample_ratio | number | True | 1 | [0.00001, 1] | How often to sample the requests. Setting to `1` will sample all requests. | +By default, service names and endpoint address for the Plugin are pre-configured in the [default configuration](https://github.com/apache/apisix/blob/master/apisix/cli/config.lua). -### Configuring the endpoint +To customize these values, add the corresponding configurations to `config.yaml`. For example: -You can configure these attributes on your configuration file (`conf/config.yaml`): - -| Name | Type | Default | Description | -|-----------------------|---------|----------------------------------------|----------------------------------------------------------------------------------------------| -| service_name | string | "APISIX" | Service name for SkyWalking reporter. | -| service_instance_name | string | "APISIX Instance Name" | Service instance name for SkyWalking reporter. Set to `$hostname` to get the local hostname. | -| endpoint_addr | string | "http://127.0.0.1:12800" | SkyWalking HTTP endpoint. For example, `http://127.0.0.1:12800`. | -| report_interval | integer | Value in the SkyWalking client library | Reporting interval time in seconds. | - -You can configure these as shown below: - -```yaml title="conf/config.yaml" +```yaml plugin_attr: skywalking: - service_name: APISIX - service_instance_name: "APISIX Instance Name" - endpoint_addr: http://127.0.0.1:12800 + report_interval: 3 # Reporting interval time in seconds. + service_name: APISIX # Service name for SkyWalking reporter. + service_instance_name: "APISIX Instance Name" # Service instance name for SkyWalking reporter. + # Set to $hostname to get the local hostname. + endpoint_addr: http://127.0.0.1:12800 # SkyWalking HTTP endpoint. ``` -### Sample code for upstream configuration - -```java title="Java with Spring Boot" -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; - -@RestController -public class TestController { - @RequestMapping("/uid/{count}") - public String getUidList(@PathVariable("count") String countStr, HttpServletRequest request) { - return "OK"; - } -} -``` +Reload APISIX for changes to take effect. -You can configure the SkyWalking agent while starting your service: - -```shell title="agent/config/agent.config" -agent.service_name=yourservername -collector.backend_service=10.110.149.175:11800 -``` +## Attributes -Then, run the script: +| Name | Type | Required | Default | Valid values | Description | +|--------------|--------|----------|---------|--------------|----------------------------------------------------------------------------| +| sample_ratio | number | True | 1 | [0.00001, 1] | Frequency of request sampling. Setting the sample ratio to `1` means to sample all requests. | -```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 & -``` +## Example -## Enable Plugin +To follow along the example, start a storage, OAP and Booster UI with Docker Compose, following [Skywalking's documentation](https://skywalking.apache.org/docs/main/next/en/setup/backend/backend-docker/). Once set up, the OAP server should be listening on `12800` and you should be able to access the UI at [http://localhost:8080](http://localhost:8080). -To enable the Plugin, you have to add it to your configuration file (`conf/config.yaml`): +Update APISIX configuration file to enable the `skywalking` plugin, which is disabled by default, and update the endpoint address: -```yaml title="conf/config.yaml" +```yaml title="config.yaml" plugins: - - ... - skywalking -``` + - ... -Once you do this, a background timer will be created to report data to the SkyWalking OAP server. +plugin_attr: + skywalking: + report_interval: 3 + service_name: APISIX + service_instance_name: APISIX Instance + endpoint_addr: http://192.168.2.103:12800 +``` -Now, you can enable the Plugin on a specific Route: +Reload APISIX for configuration changes to take effect. :::note + You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command: ```bash @@ -117,121 +94,83 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### Trace All Requests + +The following example demonstrates how you can trace all requests passing through a route. + +Create a Route with `skywalking` and configure the sampling ratio to be 1 to trace all requests: + ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "methods": ["GET"], - "uris": [ - "/uid/*" - ], +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "skywalking-route", + "uri": "/anything", "plugins": { - "skywalking": { - "sample_ratio": 1 - } + "skywalking": { + "sample_ratio": 1 + } }, "upstream": { - "type": "roundrobin", - "nodes": { - "10.110.149.175:8089": 1 - } + "nodes": { + "httpbin.org:80": 1 + }, + "type": "roundrobin" } -}' + }' ``` - - -## Example usage - -First, you need to have your SkyWalking server running. - -You can run it on Docker by: +Send a few requests to the route: ```shell -sudo docker run --name skywalking -d -p 1234:1234 -p 12800:12800 --restart always apache/skywalking-oap-server:8.7.0-es6 +curl -i "http://127.0.0.1:9080/anything" ``` -:::tip +You should receive `HTTP/1.1 200 OK` responses. -By default, SkyWalking uses H2 storage. You can also use Elasticsearch storage instead. +In [Skywalking UI](http://localhost:8080), navigate to __General Service__ > __Services__. You should see a service called `APISIX` with traces corresponding to your requests: -First, install Elasticsearch. You can do it on Docker by running: +![SkyWalking APISIX traces](https://static.apiseven.com/uploads/2025/01/15/UdwiO8NJ_skywalking-traces.png) -```shell -sudo docker run -d --name elasticsearch -p 9200:9200 -p 9300:9300 --restart always -e "discovery.type=single-node" elasticsearch:6.7.2 -``` - -Optionally, you can install Elasticsearch management page, elasticsearch-hq: +### Associate Traces with Logs -```shell -sudo docker run -d --name elastic-hq -p 5000:5000 --restart always elastichq/elasticsearch-hq -``` +The following example demonstrates how you can configure the `skywalking-logger` Plugin on a Route to log information of requests hitting the route. -Once you have Elasticsearch installed, you can start a SkyWalking server by running: +Create a Route with the `skywalking-logger` Plugin and configure the Plugin with your OAP server URI: ```shell -sudo docker run --name skywalking -d -p 1234:1234 -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 +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "skywalking-logger-route", + "uri": "/anything", + "plugins": { + "skywalking": { + "sample_ratio": 1 + }, + "skywalking-logger": { + "endpoint_addr": "http://192.168.2.103:12800" + } + }, + "upstream": { + "nodes": { + "httpbin.org:80": 1 + }, + "type": "roundrobin" + } + }' ``` -::: - -You can also install SkyWalking UI to view the data. To run it on Docker: +Generate a few requests to the route: ```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 +curl -i "http://127.0.0.1:9080/anything" ``` -You should be able to access the UI from your browser: - - +You should receive `HTTP/1.1 200 OK` responses. -Now if you make requests to APISIX: - -```shell -curl -v http://10.110.149.192:9080/uid/12 -``` - -```shell -HTTP/1.1 200 OK -OK -... -``` +In [Skywalking UI](http://localhost:8080), navigate to __General Service__ > __Services__. You should see a service called `APISIX` with a trace corresponding to your request, where you can view the associated logs: -You should be able to see the topology of all services in your SkyWalking UI: +![trace context](https://static.apiseven.com/uploads/2025/01/16/soUpXm6b_trace-view-logs.png) -![ ](../../../assets/images/plugin/skywalking-4.png) - -You should also be able to see traces from all services: - -![ ](../../../assets/images/plugin/skywalking-5.png) - -## Delete Plugin - -To remove the `skywalking` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect. - -```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "methods": ["GET"], - "uris": [ - "/uid/*" - ], - "plugins": { - }, - "upstream": { - "type": "roundrobin", - "nodes": { - "10.110.149.175:8089": 1 - } - } -}' -``` - -To completely disable the `skywalking` Plugin, i.e to stop the background report timer, you need to remove the Plugin from your configuration file (`conf/config.yaml`): - -```yaml -plugins: - - ... - # - skywalking -``` +![associated log](https://static.apiseven.com/uploads/2025/01/16/XD934LvU_associated-logs.png) diff --git a/docs/zh/latest/plugins/skywalking.md b/docs/zh/latest/plugins/skywalking.md index 421cc0571f5a..7e459be24c62 100644 --- a/docs/zh/latest/plugins/skywalking.md +++ b/docs/zh/latest/plugins/skywalking.md @@ -5,7 +5,7 @@ keywords: - API 网关 - Plugin - SkyWalking -description: 本文将介绍 API 网关 Apache APISIX 如何通过 skywalking 插件将 metrics 上报到 Apache SkyWalking（一个开源的 APM）。 +description: skywalking 插件支持与 Apache SkyWalking 集成以进行请求跟踪。 --- + + + + ## 描述 -`skywalking` 插件用于与 [Apache SkyWalking](https://github.com/apache/skywalking) 集成。 +`skywalking` 插件支持与 [Apache SkyWalking](https://skywalking.apache.org) 集成以进行请求跟踪。 -SkyWalking 使用其原生的 NGINX Lua tracer 从服务和 URI 角度提供了分布式追踪、拓扑分析以及 metrics。 +SkyWalking 使用其原生的 Nginx Lua 跟踪器从服务和 URI 角度提供跟踪、拓扑分析和指标。APISIX 支持 HTTP 协议与 SkyWalking 服务器交互。 服务端目前支持 HTTP 和 gRPC 两种协议，在 APISIX 中目前只支持 HTTP 协议。 -## 属性 - -| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | -| ------------ | ------ | ------ | ------ | ------------ | ----------------------------------------------------- | -| sample_ratio | number | 是 | 1 | [0.00001, 1] | 采样的比例。设置为 `1` 时，将对所有请求进行采样。 | - -### 如何设置 Endpoint - -你可以在配置文件（`./conf/config.yaml`）中配置以下属性： +## 静态配置 -| 名称 | 类型 | 默认值 | 描述 | -| --------------------- | ------- | ------------------------ | ------------------------------------------------------------------ | -| 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 客户端内置的值 | 上报间隔时间，单位为秒。 | +默认情况下，插件的服务名称和端点地址已在[默认配置](https://github.com/apache/apisix/blob/master/apisix/cli/config.lua)中预先配置。 -以下是配置示例： +要自定义这些值，请将相应的配置添加到 `config.yaml`。例如： -```yaml title="./conf/config.yaml" +```yaml plugin_attr: skywalking: - service_name: APISIX - service_instance_name: "APISIX Instance Name" - endpoint_addr: http://127.0.0.1:12800 -``` - -### 上游服务示例代码 - -```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"; - } -} - + report_interval: 3 # 上报间隔时间（秒）。 + service_name: APISIX # SkyWalking 记者的服务名称。 + service_instance_name: "APISIX Instance Name" # SkyWalking 记者的服务实例名称。 + # 设置为 $hostname 可获取本地主机名。 + endpoint_addr: http://127.0.0.1:12800 # SkyWalking HTTP 端点。 ``` -在启动服务前，需要配置 SkyWalking agent： +重新加载 APISIX 以使更改生效。 -```shell title="agent/config/agent.config" -agent.service_name=yourservername -collector.backend_service=10.110.149.175:11800 -``` +## 属性 -使用以下命令启动服务脚本： +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | +| ------------ | ------ | ------ | ------ | ------------ | ----------------------------------------------------- | +| sample_ratio | number | 是 | 1 | [0.00001, 1] | 请求采样频率。将采样率设置为 `1` 表示对所有请求进行采样。 | -```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 & -``` +## 示例 -## 启用插件 +要遵循示例，请按照 [Skywalking 的文档](https://skywalking.apache.org/docs/main/next/en/setup/backend/backend-docker/) 使用 Docker Compose 启动存储、OAP 和 Booster UI。设置完成后，OAP 服务器应监听 `12800`，您应该能够通过 [http://localhost:8080](http://localhost:8080) 访问 UI。 -该插件默认是禁用状态，你需要将其添加到配置文件（`./conf/config.yaml`）中才可以启用它： +更新 APISIX 配置文件以启用 `skywalking` 插件（默认情况下处于禁用状态），并更新端点地址： -```yaml title="./conf/config.yaml" +```yaml title="config.yaml" plugins: - - ... - skywalking + - ... + +plugin_attr: + skywalking: + report_interval: 3 + service_name: APISIX + service_instance_name: APISIX Instance + endpoint_addr: http://192.168.2.103:12800 ``` -配置完成后，重新加载 APISIX，此时 APISIX 会创建一个后台定时器，向 SkyWalking OAP 服务定期上报数据。 +重新加载 APISIX 以使配置更改生效。 + +::: -以下示例展示了如何在指定路由中启用 `skywalking` 插件： +以下示例展示了如何通过 Admin API 配置插件元数据： :::note @@ -128,113 +98,83 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### 跟踪所有请求 + +以下示例演示了如何跟踪通过路由的所有请求。 + +使用 `skywalking` 创建路由，并将采样率配置为 1 以跟踪所有请求： + ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "methods": ["GET"], - "uris": [ - "/uid/*" - ], +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "skywalking-route", + "uri": "/anything", "plugins": { - "skywalking": { - "sample_ratio": 1 - } + "skywalking": { + "sample_ratio": 1 + } }, "upstream": { - "type": "roundrobin", - "nodes": { - "10.110.149.175:8089": 1 - } + "nodes": { + "httpbin.org:80": 1 + }, + "type": "roundrobin" } -}' + }' ``` - - -## 测试插件 - -首先你可以通过 [Docker Compose](https://docs.docker.com/compose/install/) 启动 SkyWalking OAP 和 SkyWalking UI： - - - 在 usr/local 中创建 `skywalking.yaml` 文件。 - - ```yaml - version: "3" - services: - oap: - image: apache/skywalking-oap-server:8.9.1 - restart: always - ports: - - "12800:12800/tcp" - - ui: - image: apache/skywalking-ui:8.9.1 - restart: always - ports: - - "8080:8080/tcp" - environment: - SW_OAP_ADDRESS: http://oap:12800 - ``` - - - 使用以下命令启动上述创建的文件： - - ```shell - docker-compose -f skywalking.yaml up -d - ``` - - 完成上述操作后，就已经启动了 SkyWalking 以及 SkyWalking Web UI。你可以使用以下命令确认容器是否正常运行： - - ```shell - docker ps - ``` - -接下来你可以通过以下命令访问 APISIX： +向路由发送几个请求： ```shell -curl -v http://10.110.149.192:9080/uid/12 -``` - -``` -HTTP/1.1 200 OK -OK -... +curl -i "http://127.0.0.1:9080/anything" ``` -完成上述步骤后，打开浏览器，访问 SkyWalking 的 UI 页面，你可以看到如下服务拓扑图： +您应该收到 `HTTP/1.1 200 OK` 响应。 -![plugin_skywalking](../../../assets/images/plugin/skywalking-4.png) +在 [Skywalking UI](http://localhost:8080) 中，导航到 __General Service__ > __Services__。您应该看到一个名为 `APISIX` 的服务，其中包含与您的请求相对应的跟踪： -并且可以看到服务追踪列表： +![SkyWalking APISIX 跟踪](https://static.apiseven.com/uploads/2025/01/15/UdwiO8NJ_skywalking-traces.png) -![plugin_skywalking](../../../assets/images/plugin/skywalking-5.png) +### 将跟踪与日志关联 -## 删除插件 +以下示例演示了如何在路由上配置 `skywalking-logger` 插件，以记录到达路由的请求信息。 -当你需要禁用 `skywalking` 插件时，可通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务： +使用 `skywalking-logger` 插件创建路由，并使用你的 OAP 服务器 URI 配置该插件： ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "methods": ["GET"], - "uris": [ - "/uid/*" - ], +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "skywalking-logger-route", + "uri": "/anything", "plugins": { + "skywalking": { + "sample_ratio": 1 + }, + "skywalking-logger": { + "endpoint_addr": "http://192.168.2.103:12800" + } }, "upstream": { - "type": "roundrobin", - "nodes": { - "10.110.149.175:8089": 1 - } + "nodes": { + "httpbin.org:80": 1 + }, + "type": "roundrobin" } -}' + }' ``` -如果你想完全禁用 `skywalking` 插件，即停掉后台上报数据的定时器，就需要从配置文件（`./conf/config.yaml`）注释该插件： +生成几个对路由的请求： -```yaml title="./conf/config.yaml" -plugins: - - ... - #- skywalking +```shell +curl -i "http://127.0.0.1:9080/anything" ``` + +您应该会收到 `HTTP/1.1 200 OK` 响应。 + +在 [Skywalking UI](http://localhost:8080) 中，导航到 __General Service__ > __Services__。您应该会看到一个名为 `APISIX` 的服务，其中包含与您的请求相对应的跟踪，您可以在其中查看相关日志： + +![trace context](https://static.apiseven.com/uploads/2025/01/16/soUpXm6b_trace-view-logs.png) + +![associated log](https://static.apiseven.com/uploads/2025/01/16/XD934LvU_associated-logs.png)