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

API7 网关 AI Agent Skill：zipkin 插件

概览​

zipkin 插件会将分布式追踪数据发送到兼容 Zipkin 的采集器 使用 Zipkin v2 HTTP API。它支持通过 B3 传播请求头跨服务传递链路上下文。兼容的后端包括 Zipkin、Jaeger 和 SkyWalking（通过 Zipkin 接收器）。

适用场景​

  • 使用 Zipkin、Jaeger 或兼容的采集器进行分布式追踪。
  • 通过 B3 请求头在微服务之间传播追踪信息。
  • 通过请求头控制单个请求的采样。
  • 将 Trace ID 注入访问日志。

插件配置参考​

字段类型是否必填默认值说明
endpointstring是—Zipkin 采集器 URL（例如 http://zipkin:9411/api/v2/spans）
sample_rationumber是—采样率，范围为 0.00001 至 1
service_namestring否"APISIX"Zipkin UI 中显示的服务名称
server_addrstring否$server_addr用于上报 span 的 IPv4 地址
span_versioninteger否2Span 格式：1（旧版）或 2（默认）

B3 传播请求头​

该插件使用 B3 传播格式：

注入到上游​

请求头说明
x-b3-traceidTrace ID（16 或 32 个十六进制字符）
x-b3-spanidSpan ID（16 个十六进制字符）
x-b3-parentspanid父 span ID
x-b3-sampled采样决策（1 或 0）

从客户端提取​

请求头说明
b3单请求头格式：{traceid}-{spanid}-{sampled}-{parentspanid}
x-b3-sampled1 = 强制采样，0 = 跳过，d = 调试
x-b3-flags1 = 强制调试采样

客户端可以通过设置 x-b3-sampled: 1 覆盖单个请求的采样设置。

分步指南：启用 Zipkin 链路追踪​

1. 使用 zipkin 创建路由​

在网关组 default 中启用追踪：

a7 route create --gateway-group default -f - <<'EOF'
{
  "id": "traced-api",
  "uri": "/api/*",
  "plugins": {
    "zipkin": {
      "endpoint": "http://zipkin:9411/api/v2/spans",
      "sample_ratio": 1,
      "service_name": "my-gateway",
      "span_version": 2
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

2. 发送请求​

curl http://localhost:9080/api/hello

3. 在 Zipkin UI 中查看追踪​

打开 Zipkin UI，并搜索服务 my-gateway。

常见模式​

将追踪发送到 Jaeger​

Jaeger 支持 Zipkin v2 API：

{
  "plugins": {
    "zipkin": {
      "endpoint": "http://jaeger-collector:9411/api/v2/spans",
      "sample_ratio": 1,
      "service_name": "my-gateway"
    }
  }
}

生产环境采样（10%）​

{
  "plugins": {
    "zipkin": {
      "endpoint": "http://zipkin:9411/api/v2/spans",
      "sample_ratio": 0.1,
      "service_name": "production-gateway"
    }
  }
}

通过全局规则全局启用​

a7 global_rule create --gateway-group prod -f - <<'EOF'
{
  "id": "zipkin-global",
  "plugins": {
    "zipkin": {
      "endpoint": "http://zipkin:9411/api/v2/spans",
      "sample_ratio": 0.5,
      "service_name": "prod-gateway"
    }
  }
}
EOF

故障排查​

现象原因解决方法
Zipkin UI 中没有追踪endpoint URL 错误验证采集器可访问，并确认 URL 包含 /api/v2/spans
追踪未连接B3 请求头被移除确保中间代理转发 x-b3-* 请求头
所有请求都被采样sample_ratio: 1在生产环境降低采样率（例如 0.01–0.1）
采集器返回 400Span 版本不匹配如果采集器仅支持 v1，请尝试设置 span_version: 1
配置未生效指定了错误的网关组确保 --gateway-group 与目标集群一致

配置同步示例​

version: "1"
gateway_group: default
routes:
  - id: traced-api
    uri: /api/*
    plugins:
      zipkin:
        endpoint: http://zipkin:9411/api/v2/spans
        sample_ratio: 1
        service_name: my-gateway
        span_version: 2
    upstream:
      type: roundrobin
      nodes:
        - host: backend
          port: 8080
          weight: 1

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