Skip to main content

Crate grow_zipkin

Crate grow_zipkin 

Source
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§

blockingblocking
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.
testingtesting
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§

ZipkinAnnotation
A timestamped event on a span.
ZipkinClient
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). close also shuts down every tracing handle created through this client.
ZipkinConfig
Immutable client configuration; build it with ZipkinConfig::builder or ZipkinConfig::from_env.
ZipkinConfigBuilder
Builder for ZipkinConfig. Values set here win over the environment.
ZipkinDependencyLink
A dependency edge with Zipkin’s errorCount (0 when the server omits it).
ZipkinDependencyOptions
Window of ZipkinQueryClient::get_dependencies: either the category window (start/end) or Zipkin’s native end_ts + lookback (these win when given).
ZipkinEndpoint
Network endpoint of a span (localEndpoint / remoteEndpoint).
ZipkinQueryClient
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 §5 TraceQueryClient (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).
ZipkinReporter
Reports spans to Zipkin without OpenTelemetry: POST /api/v2/spans with a JSON array of v2 spans (202 Accepted). Spans are normalized locally first (normalize_zipkin_span), so an invalid span fails with VALIDATION before 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.
ZipkinReporterOptions
Options of ZipkinReporter.
ZipkinServerInfo
Build information of the server (GET /info).
ZipkinSpan
A Zipkin v2 span exactly as the server stores and returns it (every tag value is a string).
ZipkinSpanExporter
OpenTelemetry SpanExporter for Zipkin: maps each span with to_zipkin_span and sends the batch with a ZipkinReporter (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.
ZipkinSpanExporterOptions
Options of ZipkinSpanExporter::new.
ZipkinTraceQuery
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, tags and annotations are combined with and (Zipkin supports AND only).
ZipkinTracingOptions
Options of init_tracing_with_options.

Enums§

ZipkinExporter
The exporter built by zipkin_exporter_factory: the native Zipkin exporter or the official OTLP exporter (to an OpenTelemetry Collector).
ZipkinKind
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 limit of ZipkinQueryClient::search_traces (SPEC §5).
DEFAULT_SEARCH_WINDOW
Window of ZipkinQueryClient::search_traces when the query has no start.
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/traceMany request: 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 the ZipkinSpanExporter encodes 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 annotationQuery from exact tag matches and bare terms (joined with and); None when both are empty. VALIDATION for a term Zipkin cannot express (empty, contains and, or a key with =).
default_propagators
Default propagators of the Zipkin preset: W3C trace context + baggage and B3 single-header (b3). Add PropagatorKind::B3Multi to also inject the X-B3-* headers; every B3 propagator extracts both B3 forms.
dependencies_from_value
Decodes /api/v2/dependencies, defaulting errorCount to 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 via ZipkinSpanExporter to http://127.0.0.1:9411/api/v2/spans), propagators tracecontext, baggage, b3 composed B3-first so W3C wins on conflict. The environment fills every unset field (see tracing_config_from_env_with and ZipkinConfig::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. VALIDATION naming 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 W3C traceparent wins 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); None when 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 config from the process environment and applies the Zipkin defaults; see tracing_config_from_env_with.
tracing_config_from_env_with
Fills the unset fields of config from env and applies the Zipkin defaults (explicit > environment > default). A field still at its TracingConfig::new default counts as unset:
zipkin_exporter_factory
Builds the exporter_factory of init_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 the error tag (error, message = its value) or otel.status_code (OK/ERROR), no links. Endpoints, shared and debug stay on the raw ZipkinSpan.
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). VALIDATION without a request otherwise.
zipkin_trace_to_trace
Converts the spans of one Zipkin trace into a Trace (spans sorted); None when empty.
zipkin_traces_from_value
Keeps the well-formed traces of a response body (ZipkinSpan[][]), dropping empty ones.

Type Aliases§

ExportErrorHandler
Callback for failed exports (see ZipkinSpanExporterOptions::on_error).
ZipkinError
Service-prefixed alias of Error.