跳到主要内容

SkyWalking

skywalking 插件将 APISIX 和 API7 网关的分布式追踪发送到 Apache SkyWalking。

SkyWalking 使用其原生 NGINX Lua 追踪器，从服务和 URI 两个视角提供追踪、拓扑分析和指标。网关通过 HTTP 与 SkyWalking 服务器通信。

追踪会增加每个采样请求的处理开销。使用 sample_ratio 在追踪覆盖率和额外开销之间取得平衡；当高吞吐量路由不需要全量采样时，请使用较低的采样比例。未被选中采样的请求会跳过追踪创建，但具体性能影响取决于工作负载和收集器配置。

示例​

以下示例使用 SkyWalking OAP 11.0.0、BanyanDB 0.11.0 和 Horizon 1.0.0。请在与网关相同的环境中启动 SkyWalking 服务：

创建 SkyWalking 容器使用的网络：

docker network create gateway-skywalking-net

如果网关也在 Docker 中运行，请设置 GATEWAY_CONTAINER 并将其连接到该网络。如果网关安装在主机上，请跳过此步骤：

export GATEWAY_CONTAINER=replace-with-gateway-container-name
docker network connect gateway-skywalking-net "$GATEWAY_CONTAINER"

创建以下 Docker Compose 文件：

skywalking-compose.yaml
services:
  banyandb:
    image: apache/skywalking-banyandb:0.11.0
    command: standalone
    networks:
      - skywalking

  oap:
    image: apache/skywalking-oap-server:11.0.0
    environment:
      SW_STORAGE: banyandb
      SW_STORAGE_BANYANDB_TARGETS: banyandb:17912
    ports:
      - "127.0.0.1:12800:12800"
    depends_on:
      - banyandb
    networks:
      skywalking:
        aliases:
          - skywalking-oap

  horizon:
    image: apache/skywalking-ui:horizon-1.0.0
    environment:
      HORIZON_OAP_QUERY_URL: http://skywalking-oap:12800
      HORIZON_OAP_ADMIN_URL: http://skywalking-oap:17128
      HORIZON_AUTH_LOCAL_USERS: '[{"username":"admin","passwordHash":"$$argon2id$$v=19$$m=65536,t=3,p=4$$eemqy1r72oSXR58y8VpRqw$$Bn/dULrmJTHEi3263KfgWDEwQmUsqNLi3xwyv/DekHM","roles":["admin"]}]'
    ports:
      - "127.0.0.1:8081:8081"
    depends_on:
      - oap
    networks:
      - skywalking

networks:
  skywalking:
    name: gateway-skywalking-net
    external: true

启动服务：

docker compose -f skywalking-compose.yaml up -d

Horizon 可通过 http://localhost:8081 访问。使用用户名 admin 和密码 admin 登录。

警告

本示例中的本地用户使用公开的演示凭证。请仅在可信的本地评估环境中使用这些凭证。将 Horizon 暴露到本地环境之外前，请配置身份提供商或生成唯一的密码哈希。

下文 Admin API 和 ADC 示例配置 OAP 端点时，使用 Docker 网络中的地址 http://skywalking-oap:12800。对于安装在主机上的网关，请改用 http://127.0.0.1:12800。如果网关通过 Kubernetes 访问 OAP，请使用 http://skywalking-oap.skywalking.svc.cluster.local:12800。Ingress Controller 示例已使用 Kubernetes Service 地址。

SkyWalking OAP 服务器可用后，请根据网关的部署方式配置网关。在 API7 网关中，Dashboard 和 Admin API 默认提供 skywalking。对于 APISIX 部署，请先在网关插件列表中加载 skywalking，再设置 SkyWalking OAP 服务器的端点地址。

对于 APISIX 主机部署，请保留 config.yaml 中现有的插件列表，添加 skywalking，并将 plugin_attr.skywalking.endpoint_addr 设置为主机上公开的 OAP 端口：

config.yaml
plugins:
  # Keep the complete plugin list used by your gateway.
  - skywalking

plugin_attr:
  skywalking:
    report_interval: 3
    service_name: APISIX
    service_instance_name: APISIX Instance
    endpoint_addr: http://127.0.0.1:12800

重新加载网关，使配置变更生效。

追踪所有请求​

以下示例追踪经过某一路由的每个请求。

创建启用 skywalking 的路由，并将采样比例配置为 1，以追踪所有请求：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "skywalking-route",
    "uri": "/anything",
    "plugins": {
      "skywalking": {
        "sample_ratio": 1
      }
    },
    "upstream": {
      "nodes": {
        "httpbin.org:80": 1
      },
      "type": "roundrobin"
    }
  }'

向路由发送几次请求：

curl -i "http://127.0.0.1:9080/anything"

你应收到 HTTP/1.1 200 OK 响应。

在 Horizon 中，前往 General Service → Traces 并运行查询。你应看到 APISIX 服务的追踪：

Horizon 显示通过 APISIX 的请求所创建的追踪

将追踪与日志关联​

以下示例将已追踪路由的请求日志发送到 SkyWalking，使 Horizon 能够将每条日志与其追踪关联。

创建启用 skywalking-logger 插件的路由，并使用 OAP 服务器 URI 配置该插件：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "skywalking-logger-route",
    "uri": "/anything",
    "plugins": {
      "skywalking": {
        "sample_ratio": 1
      },
      "skywalking-logger": {
        "endpoint_addr": "http://skywalking-oap:12800"
      }
    },
    "upstream": {
      "nodes": {
        "httpbin.org:80": 1
      },
      "type": "roundrobin"
    }
  }'

向路由发送几次请求：

curl -i "http://127.0.0.1:9080/anything"

你应收到 HTTP/1.1 200 OK 响应。

在 Horizon 中，前往 General Service → Logs 并运行查询。关联的请求日志包含一个 trace 链接，单击该链接可打开对应的追踪：

Horizon 显示与追踪关联的 APISIX 请求日志