跳到主要内容
版本：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. 在路由上启用​

在网关组 default 中启用追踪：

a7 route create --gateway-group default -f - <<'EOF'
{
  "id": "traced-api",
  "uri": "/api/*",
  "plugins": {
    "skywalking": {
      "sample_ratio": 1
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 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 关联起来。

通过全局规则启用​

a7 global_rule create --gateway-group default -f - <<'EOF'
{
  "id": "skywalking-global",
  "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 与目标集群一致

配置同步示例​

version: "1"
gateway_group: default
routes:
  - id: traced-api
    uri: /api/*
    plugins:
      skywalking:
        sample_ratio: 1
    upstream:
      type: roundrobin
      nodes:
        - host: backend
          port: 8080
          weight: 1

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