使用 Zipkin 追踪请求

分布式链路能展示请求在系统中的流转方式以及各阶段的耗时。APISIX 可以使用 zipkin 插件对网关请求进行追踪插桩，并通过 Zipkin v2 HTTP API 导出采样跨度。

本指南将全局配置该插件，通过示例路由代理请求，并在 Zipkin 中验证生成的链路。

前置条件

• 安装 Docker。
• 安装 cURL，用于发送请求并验证链路。
• 完成 APISIX 快速入门教程，启动 Docker 快速入门环境。该环境会创建下文使用的 apisix-quickstart-net 网络。

启动 Zipkin

在与 APISIX 相同的 Docker 网络上启动固定版本的 Zipkin 实例。仅在环回接口上公开 Zipkin UI：

docker run -d --name zipkin \
  --network apisix-quickstart-net \
  -p 127.0.0.1:9411:9411 \
  openzipkin/zipkin:3.6.1

等待 Zipkin 准备就绪：

until curl -fsS "http://127.0.0.1:9411/health" > /dev/null; do
  sleep 1
done

本地评估配置

此 Zipkin 实例使用临时内存存储，且未配置身份认证或 TLS。在生产环境中，请配置持久存储并保护收集器端点。

配置 APISIX

在全局规则中配置 zipkin，使插件应用于所有经路由的请求，然后创建一个示例路由。如果只需追踪选定流量，请改为在单个路由或服务上配置插件。

示例使用固定标识符 zipkin、zipkin-tracing-route 和 httpbin。应用配置前，请确认这些名称尚未被使用，或在整份配置中一致地替换它们。

Admin API

创建一条全局规则，将每个采样跨度发送到 Zipkin 容器：

curl "http://127.0.0.1:9180/apisix/admin/global_rules/zipkin" -X PUT \
  -d '{
    "plugins": {
      "zipkin": {
        "endpoint": "http://zipkin:9411/api/v2/spans",
        "sample_ratio": 1
      }
    }
  }'

创建示例路由：

curl "http://127.0.0.1:9180/apisix/admin/routes/zipkin-tracing-route" -X PUT \
  -d '{
    "uri": "/anything",
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

ADC

将全局规则和示例服务添加到现有 ADC 配置中，使其他服务和全局规则仍保持期望状态：

adc.yaml

global_rules:
  zipkin:
    endpoint: "http://zipkin:9411/api/v2/spans"
    sample_ratio: 1
services:
  - name: httpbin
    routes:
      - uris:
          - /anything
        name: zipkin-tracing-route
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

预览协调结果，并确认其中没有意外更新或删除：

adc diff -f adc.yaml \
  --include-resource-type service \
  --include-resource-type global_rule

同步已审查的配置：

adc sync -f adc.yaml \
  --include-resource-type service \
  --include-resource-type global_rule

❶ 将跨度发送到 APISIX 容器可访问的 Zipkin v2 HTTP 端点。

❷ 在本地示例中采样每个请求，除非请求携带了不采样的 B3 决策。如果高吞吐量生产流量无需全量采样，请使用更低的采样率。

验证链路

通过 APISIX 发送请求：

curl "http://127.0.0.1:9080/anything"

你应会收到 HTTP/1.1 200 OK 响应。JSON 响应正文应显示 APISIX 添加到上游请求中的 B3 追踪请求头：

{
  "args": {},
  "data": "",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "*/*",
    "Host": "127.0.0.1",
    "User-Agent": "curl/8.7.1",
    "X-Amzn-Trace-Id": "Root=1-6aa8b24c-29cf898f18bbdf415ccd7b42",
    "X-B3-Parentspanid": "e1a7df5f617b3a04",
    "X-B3-Sampled": "1",
    "X-B3-Spanid": "c3a11943cd04ec70",
    "X-B3-Traceid": "b06793db23230f51187a9638e08fb772",
    "X-Forwarded-Host": "127.0.0.1:9080"
  },
  "json": null,
  "method": "GET",
  "url": "http://127.0.0.1:9080/anything"
}

等待异步导出的链路可用：

trace_ready=false
for attempt in $(seq 1 20); do
  if curl -fsS \
    "http://127.0.0.1:9411/api/v2/traces?serviceName=apisix&limit=10" | \
    grep -q '"traceId"'; then
    trace_ready=true
    break
  fi
  sleep 1
done
[ "$trace_ready" = true ]

访问 http://127.0.0.1:9411/zipkin 打开 Zipkin UI，然后选择 Run Query。你应会看到该请求的链路：

打开链路以检查其跨度：

对于本示例中代理成功的请求，默认跨度层次结构如下：

apisix.request
├── apisix.proxy
└── apisix.response_span

apisix.proxy 跨度覆盖从请求开始到 NGINX header_filter 阶段开始的时间。apisix.response_span 跨度覆盖从 header_filter 开始到 log 阶段开始的时间。

请求跨度还包含 apisix.response_source 标签，用于标识响应来自 APISIX、NGINX 还是上游服务。有关完整的插件配置和跨度版本比较，请参阅 zipkin 插件参考。

后续步骤

• 通过 Jaeger v2 内置的 Zipkin 接收器将追踪发送到 Jaeger。
• 在日志中使用追踪变量，将访问日志与请求追踪关联。