跳到主要内容

a6-plugin-skywalking

概览​

skywalking 插件将 Apache APISIX与 Apache SkyWalking 集成，用于 分布式追踪。它会为每个请求创建 entry span 和 exit span，通过 HTTP 将其上报到 SkyWalking OAP，并启用服务拓扑可视化和性能分析。

适用场景​

  • 通过 SkyWalking 追踪跨微服务请求。
  • 可视化服务拓扑和依赖关系图。
  • 分析每个路由和服务的延迟。
  • 使用 skywalking-logger 关联追踪和日志。

插件配置参考（路由/服务）​

字段类型是否必填默认值说明
sample_rationumber否1采样率范围为 0.00001 至 1（1 表示采样所有链路）

全局配置( config.yaml)​

在config.yaml下的APISIX plugin_attr中配置：

字段类型默认描述
service_name字符串"APISIX"SkyWalking UI 的服务名称
service_instance_name字符串"APISIX Instance Name"实例名称( 动态使用$hostname)
endpoint_addr字符串http://127.0.0.1:12800SkyWalking OAP HTTP 端点
report_interval整数3报告间隔( 秒)
plugin_attr:
  skywalking:
    service_name: api-gateway
    service_instance_name: "$hostname"
    endpoint_addr: http://skywalking-oap:12800
    report_interval: 5

分步操作：启用 SkyWalking 链路追踪​

1. 确保SkyWalking OAP运行​

# Docker example
docker run -d --name skywalking-oap \
  -p 12800:12800 -p 11800:11800 \
  apache/skywalking-oap-server:latest

2. 配置 APISIX 全局设置​

添加到config.yaml：

plugin_attr:
  skywalking:
    service_name: my-gateway
    service_instance_name: "$hostname"
    endpoint_addr: http://skywalking-oap:12800

3. 在路由上启用​

a6 route create -f - <<'EOF'
{
  "id": "traced-api",
  "uri": "/api/*",
  "plugins": {
    "skywalking": {
      "sample_ratio": 1
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "backend:8080": 1
    }
  }
}
EOF

4. 发送请求并查看追踪​

curl http://127.0.0.1:9080/api/hello

在配置的地址打开 SkyWalking UI 查看追踪。

常见模式​

部分采样（生产环境）​

{
  "plugins": {
    "skywalking": {
      "sample_ratio": 0.1
    }
  }
}

追踪 10% 的请求，足以用于生产流量分析，同时不会产生过多开销。

使用 skywalking-logger 关联追踪和日志​

{
  "plugins": {
    "skywalking": {
      "sample_ratio": 1
    },
    "skywalking-logger": {
      "endpoint_addr": "http://skywalking-oap:12800"
    }
  }
}

在 SkyWalking UI 中将访问日志与链路 ID 关联起来。

全局启用​

curl "$(a6 context current -o json | jq -r .server)/apisix/admin/global_rules" \
  -X PUT \
  -H "X-API-KEY: $(a6 context current -o json | jq -r .api_key)" \
  -d '{
    "id": "skywalking-global",
    "plugins": {
      "skywalking": {
        "sample_ratio": 0.5
      }
    }
  }'

Span 结构​

该插件为每个请求创建两个 span：

  • entrySpan：从请求到达到响应完成。
  • exitSpan：从调用上游开始到收到响应。

配置同步示例​

version: "1"
routes:
  - id: traced-api
    uri: /api/*
    plugins:
      skywalking:
        sample_ratio: 1
    upstream_id: my-upstream
upstreams:
  - id: my-upstream
    type: roundrobin
    nodes:
      "backend:8080": 1

故障排查​

现象原因解决方法
SkyWalking UI 中没有追踪endpoint_addr 错误从网关节点验证 OAP 是否可访问
拓扑中缺少服务service_name 不匹配检查 config.yaml 中的 plugin_attr.skywalking.service_name
开销过高生产环境使用了 sample_ratio: 1将高流量路由的采样率降低到 0.01–0.1
追踪未关联后端未进行插桩在上游服务中安装 SkyWalking Agent
插件未工作未加入插件列表确保 config.yaml 的 plugins 数组中包含 skywalking

本文根据 api7/a6 仓库中的 a6-plugin-skywalking/SKILL.md 生成。可在 AI Agent Skills 页面浏览全部 Skill。