跳到主要内容
版本：3.10.x

API7 网关 AI Agent Skill：skywalking 插件

概览​

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

适用场景​

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

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

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

全局配置（网关组）​

在 API7 企业版中，SkyWalking 端点等全局设置通常在网关组级别配置。

字段类型默认值说明
service_namestring"APISIX"SkyWalking UI 中显示的服务名称
service_instance_namestring"APISIX Instance Name"实例名称（使用 $hostname 动态生成）
endpoint_addrstringhttp://127.0.0.1:12800SkyWalking OAP HTTP 端点
report_intervalinteger3上报间隔（秒）

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

1. 确保 SkyWalking OAP 可访问​

验证 SkyWalking OAP 服务器正在运行，并且 API7 企业版网关节点可以访问它。

2. 配置网关组设置​

在 API7 企业版网关组中配置 skywalking 插件属性。

3. 在基于服务的路由上启用​

将 <gateway-group-id> 替换为 a7 gateway-group list -o json 返回的 ID，然后启用追踪：

a7 service create --gateway-group <gateway-group-id> -f - <<'EOF'
{
  "id": "traced-api-service",
  "name": "Traced API service",
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

a7 route create --gateway-group <gateway-group-id> -f - <<'EOF'
{
  "id": "traced-api",
  "name": "Traced API route",
  "paths": ["/api/*"],
  "service_id": "traced-api-service",
  "plugins": {
    "skywalking": {
      "sample_ratio": 1
    }
  }
}
EOF

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

curl http://localhost: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 关联起来。

通过全局规则启用​

请勿在创建请求体中设置 id。CLI 会根据插件名称生成全局规则 ID。

a7 global-rule create --gateway-group <gateway-group-id> -f - <<'EOF'
{
  "plugins": {
    "skywalking": {
      "sample_ratio": 0.5
    }
  }
}
EOF

Span 结构​

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

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

故障排查​

现象原因解决方法
SkyWalking UI 中没有追踪endpoint_addr 错误从网关节点验证 OAP 是否可访问
拓扑中缺少服务service_name 不匹配检查网关组配置中的服务名称
开销过高生产环境使用了 sample_ratio: 1将高流量路由的采样率降低到 0.01–0.1
追踪未关联后端未进行插桩在上游服务中安装 SkyWalking Agent
配置未生效指定了错误的网关组确保 --gateway-group 与目标网关组一致

配置同步示例​

将以下内容保存为 skywalking.yaml：

version: "1"
services:
  - id: traced-api-service
    name: Traced API service
    upstream:
      type: roundrobin
      nodes:
        - host: backend
          port: 8080
          weight: 1
routes:
  - id: traced-api
    name: Traced API route
    paths:
      - /api/*
    service_id: traced-api-service
    plugins:
      skywalking:
        sample_ratio: 1

校验该部分配置，并将其应用到目标网关组：

a7 config validate -f skywalking.yaml
a7 config sync -g <gateway-group-id> -f skywalking.yaml --delete=false

禁用删除可保留未包含在该部分配置中的资源。

本页面由 api7/a7 仓库中的 a7-plugin-skywalking/SKILL.md 生成。你可以在 AI Agent Skills 页面查看所有技能。