Skill for configuring the Apache APISIX zipkin plugin via the a6 CLI. Covers distributed tracing with Zipkin, Jaeger, or any Zipkin-compatible collector, B3 propagation headers, sampling, span versions, and trace variable logging.
The zipkin plugin sends distributed traces to Zipkin-compatible collectors
using the Zipkin v2 HTTP API. It supports B3 propagation headers for trace
context across services. Compatible backends include Zipkin, Jaeger, and
SkyWalking (via Zipkin receiver).
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
endpoint | string | Yes | — | Zipkin collector URL (e.g. http://zipkin:9411/api/v2/spans) |
sample_ratio| number |
| Yes |
| — |
| Sampling rate from 0.00001 to 1 |
service_name | string | No | "APISIX" | Service name in Zipkin UI |
server_addr | string | No | $server_addr | IPv4 address for span reporting |
span_version | integer | No | 2 | Span format: 1 (legacy) or 2 (default) |
The plugin uses B3 propagation format:
| Header | Description |
|---|---|
x-b3-traceid | Trace ID (16 or 32 hex chars) |
x-b3-spanid | Span ID (16 hex chars) |
x-b3-parentspanid | Parent span ID |
x-b3-sampled | Sampling decision (1 or 0) |
| Header | Description |
|---|---|
b3 | Single-header format: {traceid}-{spanid}-{sampled}-{parentspanid} |
x-b3-sampled | 1 = force sample, 0 = skip, d = debug |
x-b3-flags | 1 = force debug sampling |
Clients can override sampling per-request by setting x-b3-sampled: 1.
Version 2 (default, recommended):
request
├── proxy (request start → header_filter)
└── response (header_filter → log)
Version 1 (legacy):
request
├── rewrite
├── access
└── proxy
└── body_filter
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
curl http://127.0.0.1:9080/api/hello
Open http://zipkin:9411 and search for service my-gateway.
Jaeger supports the Zipkin v2 API:
{
"plugins": {
"zipkin": {
"endpoint": "http://jaeger-collector:9411/api/v2/spans",
"sample_ratio": 1,
"service_name": "my-gateway"
}
}
}
{
"plugins": {
"zipkin": {
"endpoint": "http://zipkin:9411/api/v2/spans",
"sample_ratio": 0.1,
"service_name": "production-gateway"
}
}
}
Add to 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
Available variables:
$zipkin_trace_id — Trace ID$zipkin_span_id — Span ID$zipkin_context_traceparent — W3C traceparent header{
"plugins": {
"zipkin": {
"endpoint": "http://zipkin:9411/api/v2/spans",
"sample_ratio": 1,
"server_addr": "10.0.1.5"
}
}
}