Span reporter¶
ZipkinReporter sends spans to Zipkin without OpenTelemetry: POST /api/v2/spans with a
JSON array of v2 spans
(202 Accepted). Use it for apps that build spans themselves, for importers, or in tests.
OpenTelemetry users get the same wire format from initTracing.
The span model¶
ZipkinSpan { traceId, parentId?, id, kind?, name?, timestamp?, duration?, localEndpoint?,
remoteEndpoint?, annotations?, tags?, debug?, shared? } with Endpoint { serviceName?, ipv4?,
ipv6?, port? } and Annotation { timestamp, value }. Field names on the wire are exact.
| Rule | Behaviour |
|---|---|
| Time units | timestamp and annotation timestamp: epoch microseconds; duration: microseconds |
| IDs | traceId 16 or 32 hex characters, id / parentId 16; lower-cased locally (Zipkin rejects upper case with 400) |
kind |
CLIENT, SERVER, PRODUCER, CONSUMER (any case in, upper case out) or absent (internal) |
| Tags | every value becomes a string (true → "true", 7 → "7", arrays/objects → JSON); Zipkin rejects the whole batch for a boolean tag |
| Names | Zipkin lower-cases service and span names on ingest (Send Order → send order) |
| Validation | an invalid span throws VALIDATION before anything is sent |
report¶
Sends spans. An empty list sends nothing; more than maxBatchSize spans (default 512) go in
several POSTs, in order. Ingest is idempotent (Zipkin merges spans by id), so 5xx, 429 and network
errors are retried; 400 and 413 are permanent VALIDATION errors. With in-memory storage the spans
are queryable as soon as the call returns; persistent backends may lag (use
waitForTrace).
const now = Date.now() * 1000;
await client.reporter.report([
{
traceId: "5af7183fb1d4cf5f0a6665df1d0a9b8c",
id: "0000000000000001",
kind: "SERVER",
name: "GET /orders",
timestamp: now,
duration: 120_000,
localEndpoint: { serviceName: "frontend" },
annotations: [{ timestamp: now + 1_000, value: "cache.miss" }],
tags: { "http.method": "GET", cached: true }, // → "true"
},
]);
use grow_zipkin::{ZipkinEndpoint, ZipkinKind, ZipkinSpan};
client
.reporter()
.report(&[ZipkinSpan::new("5af7183fb1d4cf5f0a6665df1d0a9b8c", "0000000000000001")
.with_kind(ZipkinKind::Server)
.with_name("GET /orders")
.with_local_service("frontend")
.with_remote_endpoint(ZipkinEndpoint::service("db"))
.with_timing(now_micros, 120_000)
.with_tag("http.method", "GET")])
.await?;
now := time.Now().UnixMicro()
err := client.Reporter().Report(ctx, []zipkin.ZipkinSpan{{
TraceID: "5af7183fb1d4cf5f0a6665df1d0a9b8c", ID: "0000000000000001",
Kind: zipkin.KindServer, Name: "GET /orders", Timestamp: now, Duration: 120_000,
LocalEndpoint: &zipkin.Endpoint{ServiceName: "frontend"},
Annotations: []zipkin.Annotation{{Timestamp: now + 1000, Value: "cache.miss"}},
Tags: map[string]string{"http.method": "GET"},
}})
import grow_zipkin as sdk
client.reporter.report([
sdk.ZipkinSpan(
trace_id="5af7183fb1d4cf5f0a6665df1d0a9b8c",
id="0000000000000001",
kind="SERVER",
name="GET /orders",
timestamp=now_us,
duration=120_000,
local_endpoint=sdk.ZipkinEndpoint("frontend"),
tags={"http.method": "GET", "http.status_code": 200}, # → "200"
),
# the wire form (camelCase keys) is accepted too
{"traceId": "5af7183fb1d4cf5f0a6665df1d0a9b8c", "id": "0000000000000002",
"parentId": "0000000000000001", "name": "select", "kind": "CLIENT"},
])
Instant now = Instant.now();
client.reporter().report(List.of(
ZipkinSpan.builder("5af7183fb1d4cf5f0a6665df1d0a9b8c", "0000000000000001")
.kind(ZipkinKind.SERVER)
.name("GET /orders")
.localServiceName("frontend")
.timestamp(now)
.duration(Duration.ofMillis(120))
.annotation(now.toEpochMilli() * 1000 + 1000, "cache.miss")
.tag("http.method", "GET")
.tag("http.status_code", 200)
.build()));
Standalone reporter and options¶
A reporter built from a config owns its connections (close it). Options: compression
(gzip sends Content-Encoding: gzip; default none), maxBatchSize (default 512) and
endpoint (default the config's endpoint, i.e. GROW_ZIPKIN_ENDPOINT >
OTEL_EXPORTER_ZIPKIN_ENDPOINT > <url>/api/v2/spans).