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 service and route with zipkin

Replace <gateway-group-id> with the ID returned by a7 gateway-group list -o json, then enable tracing:

a7 service create --gateway-group <gateway-group-id> -f - <<'EOF'
{
  "id": "traced-api-service",
  "name": "Traced API service",
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

a7 route create --gateway-group <gateway-group-id> -f - <<'EOF'
{
  "id": "traced-api",
  "name": "Traced API route",
  "paths": ["/api/*"],
  "service_id": "traced-api-service",
  "plugins": {
    "zipkin": {
      "endpoint": "http://zipkin:9411/api/v2/spans",
      "sample_ratio": 1,
      "service_name": "my-gateway",
      "span_version": 2
    }
  }
}
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

Do not set an id in the create payload. The CLI derives the Global Rule ID from the plugin name.

a7 global-rule create --gateway-group <gateway-group-id> -f - <<'EOF'
{
  "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

Save the following as zipkin.yaml:

version: "1"
services:
  - id: traced-api-service
    name: Traced API service
    upstream:
      type: roundrobin
      nodes:
        - host: backend
          port: 8080
          weight: 1
routes:
  - id: traced-api
    name: Traced API route
    paths:
      - /api/*
    service_id: traced-api-service
    plugins:
      zipkin:
        endpoint: http://zipkin:9411/api/v2/spans
        sample_ratio: 1
        service_name: my-gateway
        span_version: 2

Validate and apply this partial configuration to the target gateway group:

a7 config validate -f zipkin.yaml
a7 config sync -g <gateway-group-id> -f zipkin.yaml --delete=false

Disabling deletion preserves resources that are not included in this partial configuration.

---

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