跳到主要内容

a6-plugin-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 覆盖单个请求的采样设置。

Span 版本​

版本 2（默认，推荐）：

request
├── proxy      (request start → header_filter)
└── response   (header_filter → log)

版本 1（旧版）：

request
├── rewrite
├── access
└── proxy
    └── body_filter

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

1. 创建带Zipkin的路径​

a6 route create -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": {
      "backend:8080": 1
    }
  }
}
EOF

2. 发送请求​

curl http://127.0.0.1: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"
    }
  }
}

在访问日志中记录追踪 ID​

添加到APISIX config.yaml：

plugin_attr:
  zipkin:
    set_ngx_var: true

nginx_config:
  http:
    access_log_format: '{"trace_id":"$zipkin_trace_id","span_id":"$zipkin_span_id","traceparent":"$zipkin_context_traceparent"}'
    access_log_format_escape: json

可用变量:

  • $zipkin_trace_id——追踪 ID
  • $zipkin_span_id— SPAN ID
  • $zipkin_context_traceparent— W3C traceparent标头

外部 IP 地址​

{
  "plugins": {
    "zipkin": {
      "endpoint": "http://zipkin:9411/api/v2/spans",
      "sample_ratio": 1,
      "server_addr": "10.0.1.5"
    }
  }
}

配置同步示例​

version: "1"
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_id: my-upstream
upstreams:
  - id: my-upstream
    type: roundrobin
    nodes:
      "backend:8080": 1

故障排查​

现象原因解决方法
Zipkin UI 中没有追踪endpoint URL 错误验证采集器可访问，并确认 URL 包含 /api/v2/spans
追踪未连接B3 请求头被移除确保中间代理转发 x-b3-* 请求头
所有请求都被采样sample_ratio: 1在生产环境降低采样率（例如 0.01–0.1）
采集器返回 400Span 版本不匹配如果采集器仅支持 v1，请尝试设置 span_version: 1
日志中缺少追踪变量未启用 set_ngx_var在 config.yaml 中设置 plugin_attr.zipkin.set_ngx_var: true

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