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

Step-by-Step: Enable Zipkin Tracing

1. Create a route with zipkin

Enable tracing for gateway group default:

a7 route create --gateway-group default -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": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

2. Send a request

curl http://localhost:9080/api/hello

3. View traces in Zipkin UI

Open the Zipkin UI 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"
    }
  }
}

Enable globally via Global Rule

a7 global_rule create --gateway-group prod -f - <<'EOF'
{
  "id": "zipkin-global",
  "plugins": {
    "zipkin": {
      "endpoint": "http://zipkin:9411/api/v2/spans",
      "sample_ratio": 0.5,
      "service_name": "prod-gateway"
    }
  }
}
EOF

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	Ensure intermediate proxies forward x-b3-* headers
All requests sampled	sample_ratio: 1	Lower for production (e.g. 0.01-0.1)
400 from collector	Span version mismatch	Try span_version: 1 if collector only supports v1
Config not applied	Wrong gateway group specified	Ensure --gateway-group matches the desired cluster

Config Sync Example

version: "1"
gateway_group: default
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:
      type: roundrobin
      nodes:
        - host: backend
          port: 8080
          weight: 1

---

This page is generated from a7-plugin-zipkin/SKILL.md in the api7/a7 repository. Browse all skills on the AI Agent Skills page.