zipkin

Sends traces to a Zipkin collector.

Category ObservabilityAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin zipkinPriority 12011

What it does

zipkin traces the requests that reach the route or other object it is added to. It sends their spans in batches to a Zipkin collector, each batch a POST to the URL under Endpoint. Sample ratio sets the share of requests that are traced, 0.1 for a tenth of them.

Every span names the gateway under Service name, api-gateway in the example. A request that already carries the B3 sampling headers decides for itself whether it is traced, whatever the ratio.

When to use it

• A slow request to the orders API has to be followed from the gateway to the backend, in the Zipkin the teams already use.
• Only a share of the traffic should be traced, a tenth for example, so the collector is not sent a span for every request.
• Several gateways report to one collector, each under a service name of its own.
• The gateway should report the address clients reach it at, not the address of the node that accepted the request.

Not for request counts and response times per route — see prometheus (Exposes request metrics for Prometheus) or a record of each request, sent to an HTTP endpoint — see http-logger (Sends request logs to an HTTP endpoint in batches).

Set it up

Trace a tenth of the requests under your own service name

Set Endpoint to http://zipkin.internal:9411/api/v2/spans, set Sample ratio to 0.1 and set Service name to api-gateway.

zipkin · as the console saves it

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

Things to know

• Endpoint — The spans arrive as a POST to the whole URL, path included, /api/v2/spans in the example.
• Service name — Every span the gateway sends carries this name as serviceName.
• Sample ratio — A request that carries the B3 sampling headers decides for itself; this ratio is read only where the client left the decision open.
• Sample ratio — A ratio above 1, 1.5 for example, is refused when you save.
• Server address — A host name in place of an IPv4 address is refused when you save.
• Span version — Only 1 and 2 are accepted; 3 is refused when you save.
• AdviceStart busy routes with a small Sample ratio and raise it while the collector keeps up.

Settings

The fields as the console shows them, section by section.

EndpointendpointstringRequired

The whole collector URL a batch of spans is posted to.

example http://zipkin.internal:9411/api/v2/spans

Sample ratiosample_rationumberRequired

0.00001 to 1

Service nameservice_namestringdefault APISIX

The name this gateway reports itself under on every span it sends.

Server addressserver_addrstring

The IPv4 address this gateway reports itself at; left unset it reports the address the request was accepted on.

pattern

^[0-9]{1,3}.[0-9]{1,3}.[0-9]{1,3}.[0-9]{1,3}$

Span versionspan_versionintegerdefault 2

Version 1 reports a child span for each phase of the request; version 2 reports a proxy span and a response span in their place.

one of 1, 2

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.