moonming/a6-plugin-zipkin

a6-plugin-zipkin

Overview

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).

When to Use

• Distributed tracing with Zipkin, Jaeger, or compatible collectors
• B3 header propagation across microservices
• Per-request sampling control via headers
• Trace ID injection into access logs

Plugin Configuration Reference

| 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) |

B3 Propagation Headers

The plugin uses B3 propagation format:

Injected to upstream

| 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) |

Extracted from client

| 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.

Span Versions

Version 2 (default, recommended):

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

Version 1 (legacy):

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

Step-by-Step: Enable Zipkin Tracing

1. Create a route with 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. Send a request

curl http://127.0.0.1:9080/api/hello

3. View traces in Zipkin UI

Open http://zipkin:9411 and search for service my-gateway.

Common Patterns

Send traces to Jaeger

Jaeger supports the Zipkin v2 API:

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

Production sampling (10%)

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

Trace IDs in access logs

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

External IP address

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

Config Sync Example

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

Troubleshooting

| Symptom | Cause | Fix | |---------|-------|-----| | No traces in Zipkin UI | Wrong endpoint URL | Verify collector is reachable; must include /api/v2/spans | | Traces not connected | B3 headers stripped by proxy | Ensure intermediate proxies forward x-b3-* headers | | All requests sampled | sample_ratio: 1 | Lower for production (e.g. 0.01-0.1) | | Missing trace variables in logs | set_ngx_var not enabled | Set plugin_attr.zipkin.set_ngx_var: true in config.yaml | | 400 from collector | Span version mismatch | Try span_version: 1 if collector only supports v1 |