Expand description
§grow-zipkin
Rust SDK for Zipkin by Grow Codes.
use grow_zipkin::tracing::{traced, TracingConfig};
use grow_zipkin::{ZipkinClient, ZipkinConfig, ZipkinSpan, ZipkinKind};
// Export OpenTelemetry spans to Zipkin (v2 JSON to /api/v2/spans, W3C + B3 propagation).
let tracing = grow_zipkin::init_tracing(TracingConfig::new("checkout"))?;
traced("charge-card", async { Ok::<_, std::io::Error>(()) }).await.ok();
tracing.shutdown().await?;
// Report spans without OpenTelemetry and read them back.
let client = ZipkinClient::new(ZipkinConfig::from_env()?)?;
let span = ZipkinSpan::new("5af7183fb1d4cf5f0a6665df1d0a9b8c", "0000000000000001")
.with_kind(ZipkinKind::Server)
.with_name("get /orders")
.with_local_service("checkout")
.with_timing(1_795_034_515_005_000, 1_000);
client.reporter().report(&[span]).await?;
let trace = client.query().get_trace("5af7183fb1d4cf5f0a6665df1d0a9b8c").await?;
println!("{} spans", trace.map_or(0, |t| t.spans.len()));
client.close().await;Modules: ZipkinClient (health, ping, server version), ZipkinReporter (direct span
reporting), ZipkinQueryClient (the v2 query API and the category TraceQueryClient),
ZipkinSpanExporter (OpenTelemetry exporter, own implementation — the
opentelemetry-zipkin crate is discontinued), init_tracing (the Zipkin preset) and the
tracing category helpers.
Features: blocking (a blocking client), testing (in-memory fakes and the conformance
runner)
, tower and reqwest-middleware (tracing instrumentation)
.
Re-exports§
pub use crate::core::Error;pub use crate::core::ErrorCode;pub use crate::core::HealthStatus;pub use crate::core::Result;pub use crate::core::RetryPolicy;pub use crate::core::Secret;
Modules§
- blocking
blocking - Blocking wrapper (feature
blocking). Each client owns a tokio runtime with one worker thread, so background work (batched exports, retries’ timers) keeps running between blocking calls. - core
- Shared core: errors, configuration, secrets in config, redaction, retries and transport.
- testing
testing - Test support (feature
testing): in-memory fakes and the conformance runner (SPEC §6). - tracing
- Tracing category (SPEC §5), built on the OpenTelemetry SDK: setup, span helpers, propagation, framework adapters and the trace query model.
Structs§
- Zipkin
Annotation - A timestamped event on a span.
- Zipkin
Client - Async client for Zipkin (port 9411): health, ping and server version, plus the query API
(
query), the direct span reporter (reporter) and tracing setup (init_tracing). Cheap to clone (clones share one connection pool).closealso shuts down every tracing handle created through this client. - Zipkin
Config - Immutable client configuration; build it with
ZipkinConfig::builderorZipkinConfig::from_env. - Zipkin
Config Builder - Builder for
ZipkinConfig. Values set here win over the environment. - Zipkin
Dependency Link - A dependency edge with Zipkin’s
errorCount(0 when the server omits it). - Zipkin
Dependency Options - Window of
ZipkinQueryClient::get_dependencies: either the category window (start/end) or Zipkin’s nativeend_ts+lookback(these win when given). - Zipkin
Endpoint - Network endpoint of a span (
localEndpoint/remoteEndpoint). - Zipkin
Query Client - Reads traces back from Zipkin (port 9411): the native v2 query API
(
get_trace_spans,get_traces,get_trace_many,list_services,list_spans,list_remote_services,get_dependencies,autocomplete_keys,autocomplete_values) and the SPEC §5TraceQueryClient(get_trace,search_traces,list_operations,wait_for_trace) on top of it. Every call is a GET (retried on 5xx, 429 and network errors). - Zipkin
Reporter - Reports spans to Zipkin without OpenTelemetry:
POST /api/v2/spanswith a JSON array of v2 spans (202 Accepted). Spans are normalized locally first (normalize_zipkin_span), so an invalid span fails withVALIDATIONbefore anything is sent. Ingest is idempotent (Zipkin merges spans by id), so 5xx, 429 and network errors are retried; a 400 or 413 is permanent. - Zipkin
Reporter Options - Options of
ZipkinReporter. - Zipkin
Server Info - Build information of the server (
GET /info). - Zipkin
Span - A Zipkin v2 span exactly as the server stores and returns it (every tag value is a string).
- Zipkin
Span Exporter - OpenTelemetry
SpanExporterfor Zipkin: maps each span withto_zipkin_spanand sends the batch with aZipkinReporter(POST /api/v2/spans, JSON v2, gzip by default, retries on 5xx/429/network errors). A failed batch is reported to the span processor and dropped. - Zipkin
Span Exporter Options - Options of
ZipkinSpanExporter::new. - Zipkin
Trace Query - Filter of
ZipkinQueryClient::get_traces(GET /api/v2/traces). Every field is optional; unset fields use the server defaults (endTs= now,lookback= 24 h,limit= 10).annotation_query,tagsandannotationsare combined withand(Zipkin supports AND only). - Zipkin
Tracing Options - Options of
init_tracing_with_options.
Enums§
- Zipkin
Exporter - The exporter built by
zipkin_exporter_factory: the native Zipkin exporter or the official OTLP exporter (to an OpenTelemetry Collector). - Zipkin
Kind - Zipkin span kind; an absent kind means internal (local) work.
Constants§
- DEFAULT_
MAX_ BATCH_ SIZE - Default number of spans per POST (SPEC batch default).
- DEFAULT_
SEARCH_ LIMIT - Default
limitofZipkinQueryClient::search_traces(SPEC §5). - DEFAULT_
SEARCH_ WINDOW - Window of
ZipkinQueryClient::search_traceswhen the query has nostart. - DEFAULT_
TRACING_ PROTOCOL - Default protocol of the Zipkin preset: Zipkin v2 JSON to
/api/v2/spans. - DEFAULT_
URL - Endpoint used when neither the builder nor the environment sets one.
- ENV_
OTEL_ ZIPKIN_ ENDPOINT - OpenTelemetry’s Zipkin exporter endpoint (a full spans URL).
- ENV_
ZIPKIN_ URL - Vendor variable checked after
GROW_ZIPKIN_URL. - REMOTE_
SERVICE_ KEYS - Span attributes that name the remote service of a CLIENT/PRODUCER span, by precedence.
- SPANS_
PATH - Path of the Zipkin v2 span ingest API.
- TRACE_
MANY_ CHUNK - Most trace ids sent in one
/api/v2/traceManyrequest: 100 × 33 characters keeps the request line under Armeria’s default HTTP/1 limit of 4096 bytes. - UNKNOWN_
SERVICE - Service name used when the resource has no
service.name.
Functions§
- annotation_
to_ event - Decodes an annotation into an event: a value of the form
{"<name>": {…attributes}}(how theZipkinSpanExporterencodes an event with attributes) becomes that name and attributes; any other value is the event name with no attributes. - attribute_
to_ tag - Converts an OpenTelemetry attribute value to a Zipkin tag: strings as-is, numbers and
booleans as text (
7,1.5,2,true), arrays as JSON (["a","b"],[1,2]). - base_
from_ endpoint - The server base URL of a spans endpoint: strips one trailing
/api/v2/spans(and slashes). - build_
annotation_ query - Builds a Zipkin
annotationQueryfrom exact tag matches and bare terms (joined withand);Nonewhen both are empty.VALIDATIONfor a term Zipkin cannot express (empty, containsand, or a key with=). - default_
propagators - Default propagators of the Zipkin preset: W3C trace context + baggage and B3 single-header
(
b3). AddPropagatorKind::B3Multito also inject theX-B3-*headers; every B3 propagator extracts both B3 forms. - dependencies_
from_ value - Decodes
/api/v2/dependencies, defaultingerrorCountto 0, sorted by parent then child. - init_
tracing - Sets up OpenTelemetry tracing for Zipkin (SPEC §5) with the process environment; see
init_tracing_with_options. Must be called inside a tokio runtime. - init_
tracing_ with_ options - Sets up OpenTelemetry tracing for Zipkin. Defaults: protocol
native(Zipkin v2 JSON viaZipkinSpanExportertohttp://127.0.0.1:9411/api/v2/spans), propagatorstracecontext, baggage, b3composed B3-first so W3C wins on conflict. The environment fills every unset field (seetracing_config_from_env_withandZipkinConfig::from_env). - normalize_
zipkin_ span - Normalizes one span for ingest (the rules Zipkin enforces, applied locally so one bad span
never makes the server reject the whole batch): ids lower-cased and validated, zero
timestamps/durations and empty fields dropped, annotations need a value and a timestamp.
VALIDATIONnaming the problem otherwise. - order_
propagators - The order in which propagators are composed: B3 (
b3,b3multi) first, every other propagator after it in the given order, duplicates removed. On extract, later propagators overwrite earlier ones, so W3Ctraceparentwins when it and B3 disagree. - spans_
endpoint <base>/api/v2/spans, appended once: a base that already ends with the spans path is kept, a gateway prefix is preserved and trailing slashes are dropped.- strings_
from_ value - Decodes a string list response (
string[]), skipping non-strings. - summarize_
zipkin_ trace - Summarises one Zipkin trace (root = the span without a parent in the trace, else the
earliest);
Nonewhen empty. - tag_
value - Converts a tag value to Zipkin’s string form: strings as-is, numbers and booleans as text
(
7,1.5,true), anything else as JSON (null→"null"). - to_
zipkin_ span - Maps a finished OpenTelemetry span to a Zipkin v2 span (identical in every language of this SDK; based on the OpenTelemetry Zipkin exporter specification):
- tracing_
config_ from_ env - Fills the unset fields of
configfrom the process environment and applies the Zipkin defaults; seetracing_config_from_env_with. - tracing_
config_ from_ env_ with - Fills the unset fields of
configfromenvand applies the Zipkin defaults (explicit > environment > default). A field still at itsTracingConfig::newdefault counts as unset: - zipkin_
exporter_ factory - Builds the
exporter_factoryofinit_tracing_with: - zipkin_
span_ to_ span - Converts a Zipkin span into the SPEC §5 model: trace id padded to 32 characters, kind
lower-cased (absent →
internal),service_name=localEndpoint.serviceName(or""), attributes = tags, annotations → events, status from theerrortag (error, message = its value) orotel.status_code(OK/ERROR), no links. Endpoints,sharedanddebugstay on the rawZipkinSpan. - zipkin_
spans_ from_ value - Keeps the well-formed spans of a response body (
ZipkinSpan[]). - zipkin_
trace_ id - Lower-cases and validates a Zipkin trace id (16 or 32 hex characters, not all zero).
VALIDATIONwithout a request otherwise. - zipkin_
trace_ to_ trace - Converts the spans of one Zipkin trace into a
Trace(spans sorted);Nonewhen empty. - zipkin_
traces_ from_ value - Keeps the well-formed traces of a response body (
ZipkinSpan[][]), dropping empty ones.
Type Aliases§
- Export
Error Handler - Callback for failed exports (see
ZipkinSpanExporterOptions::on_error). - Zipkin
Error - Service-prefixed alias of
Error.