跳到主要内容

zipkin

Zipkin 是一个开源的分布式追踪系统。zipkin 插件对 APISIX 进行插桩，并根据 Zipkin API 规范 将追踪信息发送到 Zipkin。

该插件还可以将追踪信息发送到其他兼容的收集器，例如 Jaeger 和 Apache SkyWalking，它们都支持 Zipkin v1 和 v2 API。

示例​

下面的示例展示了使用 zipkin 插件的不同用例。

发送追踪到 Zipkin​

以下示例展示了如何使用 Zipkin API v2 追踪对路由的请求并将追踪信息发送到 Zipkin。你还将了解 span v2 和 span v1 之间的区别。

在 Docker 中启动一个 Zipkin 实例：

docker run -d --name zipkin -p 9411:9411 openzipkin/zipkin

创建一个带有 zipkin 插件的路由并使用默认的 span v2：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "zipkin-tracing-route",
    "uri": "/anything",
    "plugins": {
      "zipkin": {
        "endpoint": "http://127.0.0.1:9411/api/v2/spans",
        "sample_ratio": 1,
        "span_version": 2
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org": 1
      }
    }
  }'

❶ 根据需要调整 Zipkin HTTP 端点的 IP 地址。

❷ 将采样率配置为 1 以追踪每个请求。

❸ 将 span 版本设置为 2。

发送请求到该路由：

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

你应该收到类似于以下的 HTTP/1.1 200 OK 响应：

{
  "args": {}, 
  "data": "", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept": "*/*", 
    "Host": "127.0.0.1", 
    "User-Agent": "curl/7.64.1", 
    "X-Amzn-Trace-Id": "Root=1-65af2926-497590027bcdb09e34752b78", 
    "X-B3-Parentspanid": "347dddedf73ec176", 
    "X-B3-Sampled": "1", 
    "X-B3-Spanid": "429afa01d0b0067c", 
    "X-B3-Traceid": "aea58f4b490766eccb08275acd52a13a", 
    "X-Forwarded-Host": "127.0.0.1"
  }, 
  ...
}

导航到 http://127.0.0.1:9411/zipkin 的 Zipkin web UI 并点击 Run Query，你应该看到与请求对应的追踪：

trace-from-request

点击 Show 查看更多追踪详情：

v2-trace-spans

请注意，使用 span v2，每个被追踪的请求都会创建以下 span：

request
├── proxy
└── response

其中 proxy 代表从请求开始到 header_filter 开始的时间，response 代表从 header_filter 开始到 log 开始的时间。

现在，更新路由上的插件以使用 span v1：

curl "http://127.0.0.1:9180/apisix/admin/routes/zipkin-tracing-route" -X PATCH \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "plugins": {
      "zipkin": {
        "span_version": 1
      }
    }
  }'

发送另一个请求到该路由：

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

在 Zipkin web UI 中，你应该看到一个新的追踪，其详情类似于以下内容：

v1-trace-spans

请注意，使用较旧的 span v1，每个被追踪的请求都会创建以下 span：

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

发送追踪到 Jaeger​

以下示例展示了如何追踪对路由的请求并将追踪信息发送到 Jaeger。

在 Docker 中启动一个 Jaeger 实例：

docker run -d --name jaeger \
  -e COLLECTOR_ZIPKIN_HOST_PORT=9411 \
  -p 16686:16686 \
  -p 9411:9411 \
  jaegertracing/all-in-one

创建一个带有 zipkin 插件的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "zipkin-tracing-route",
    "uri": "/anything",
    "plugins": {
      "zipkin": {
        "endpoint": "http://127.0.0.1:9411/api/v2/spans",
        "sample_ratio": 1
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org": 1
      }
    }
  }'

❶ 根据需要调整 Zipkin HTTP 端点的 IP 地址。

❷ 将采样率配置为 1 以追踪每个请求。

发送请求到该路由：

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

你应该收到 HTTP/1.1 200 OK 响应。

导航到 http://127.0.0.1:16686 的 Jaeger web UI，选择 APISIX 作为服务，然后点击 Find Traces，你应该看到与请求对应的追踪：

jaeger-traces

同样，点击进入追踪后，你应该会发现更多 span 详情：

jaeger-details

在日志记录中使用追踪变量​

以下示例展示了如何配置 zipkin 插件以设置以下内置变量，这些变量可用于日志插件或访问日志：

  • zipkin_context_traceparent: trace parent ID
  • zipkin_trace_id: 当前 span 的追踪 ID
  • zipkin_span_id: 当前 span 的 span ID

按如下方式更新 配置文件：

conf/config.yaml
nginx_config:
  http:
    enable_access_log: true
    access_log_format: '{"time": "$time_iso8601","zipkin_context_traceparent": "$zipkin_context_traceparent","zipkin_trace_id": "$zipkin_trace_id","zipkin_span_id": "$zipkin_span_id","remote_addr": "$remote_addr"}'
    access_log_format_escape: json
plugin_attr:
  zipkin:
    set_ngx_var: true

❶ access_log_format: 自定义访问日志格式以使用 zipkin 插件变量。

❷ set_ngx_var: 设置 zipkin 变量。

重新加载 APISIX 以使配置更改生效。

生成请求时，你应该看到类似于以下的访问日志条目：

{"time": "23/Jan/2024:06:28:00 +0000","zipkin_context_traceparent": "00-61bce33055c56f5b9bec75227befd142-13ff3c7370b29925-01","zipkin_trace_id": "61bce33055c56f5b9bec75227befd142","zipkin_span_id": "13ff3c7370b29925","remote_addr": "172.28.0.1"}