Expand description
§grow-jaeger
Rust SDK for Jaeger by Grow Codes.
use grow_jaeger::tracing::{traced, TracingConfig, TraceSearchQuery};
use grow_jaeger::{init_tracing, JaegerClient, JaegerConfig};
// Export spans to Jaeger over OTLP (http/protobuf on 4318 unless configured otherwise).
let tracing = init_tracing(TracingConfig::new("checkout"))?;
traced("charge-card", async { Ok::<_, std::io::Error>(()) }).await.ok();
tracing.shutdown().await?;
// Read them back through the query API (16686).
let client = JaegerClient::new(JaegerConfig::from_env()?)?;
let summaries = client.query().search_traces(&TraceSearchQuery::service("checkout")).await?;
println!("{} traces", summaries.len());
client.close().await;Modules: JaegerClient (health, version, sampling strategy), JaegerQueryClient
(get_trace, find_traces, search_traces, list_services, list_operations,
get_operations, get_dependencies), init_tracing (OTLP preset, presets, remote
sampling), JaegerRemoteSampler 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 (exports, sampler polling, retries’ timers) keeps running between blocking calls. - core
- Shared core: errors, configuration, secrets in config, redaction, retries and transport.
- normalize
- Conversions from Jaeger’s wire formats to the normalized model of the tracing category:
OTLP/JSON
TracesData(the v3 API), the legacy UI model (/api/traces/{id}), trace summaries (/api/v3/trace-summaries) and dependency links (/api/dependencies). - 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§
- GetTrace
Options - Options of
JaegerQueryClient::get_trace_with. - Jaeger
Build Info - Build information embedded in the Jaeger UI page (
JAEGER_VERSION). - Jaeger
Client - Async client for Jaeger. Cheap to clone (clones share one connection pool).
- Jaeger
Config - Immutable client configuration; build it with
JaegerConfig::builderorJaegerConfig::from_env.Debugoutput redacts every credential. - Jaeger
Config Builder - Builder for
JaegerConfig. Values set here win over the environment. - Jaeger
Query Client - Query client for the Jaeger HTTP query API. Get it with
JaegerClient::queryor build it withJaegerQueryClient::new. Cheap to clone; implementsTraceQueryClient. - Jaeger
Remote Sampler - OpenTelemetry head sampler driven by Jaeger remote sampling: it polls
GET <sampling_url>?service=<service>every poll interval and applies the strategy (see the module docs for the rule). Use it withinit_tracing_with_remote_sampler(which wraps it in a parent-based sampler) orSdkTracerProvider::builder().with_sampler(…). Cheap to clone (clones share the strategy and the poller).closestops polling. - Jaeger
Tracing Handle - A running Jaeger tracing setup (SPEC §5
TracingHandleplus the endpoint and the remote sampler). Cheap to clone. Without remote sampling it wraps the categoryTracingHandle(tracing_handle). - Jaeger
Tracing Options - Options of
init_tracing_with_options. - List
Operations Options - Options of
JaegerQueryClient::list_operationsandJaegerQueryClient::get_operations. - Operation
- One operation of a service, as returned by
JaegerQueryClient::get_operations. - Operation
Strategy - Sampling probability of one operation (span name).
- Rate
Limiter - Token bucket that lets at most
credits_per_secondtraces through per second, with a burst ofmax(credits_per_second, 1). It starts full, so a rate of 0 lets the first trace through and then none (Jaeger behaviour). - Remote
Sampler Options - Options of
JaegerRemoteSampler::with_options. - Sampling
Preset - A named head-sampling choice for
TracingConfig. - Sampling
Strategy - A Jaeger remote sampling strategy (the
/sampling?service=response).
Enums§
- Remote
Sampling - Remote sampling for
JaegerTracingOptions. - Strategy
Type - Strategy type of a
SamplingStrategy.
Constants§
- DEFAULT_
DEPENDENCY_ LOOKBACK - Dependency lookback when no start is given: 24 hours.
- DEFAULT_
GET_ TRACE_ WINDOW - Time hint
JaegerQueryClient::get_tracesends: the last 7 days. - DEFAULT_
INITIAL_ SAMPLING_ RATE - Probability applied until the first strategy arrives (Jaeger and OpenTelemetry default).
- DEFAULT_
OTLP_ GRPC_ ENDPOINT - Default OTLP/gRPC endpoint of a Jaeger all-in-one or collector.
- DEFAULT_
OTLP_ HTTP_ ENDPOINT - Default OTLP/HTTP traces endpoint of a Jaeger all-in-one or collector.
- DEFAULT_
SAMPLING_ POLL_ INTERVAL - How often a
JaegerRemoteSamplerpolls by default (Jaeger default: 1 minute). - DEFAULT_
SAMPLING_ URL - Remote sampling endpoint (port 5778) used when neither the builder nor the environment sets one.
- DEFAULT_
SEARCH_ WINDOW - Search window when a
TraceSearchQueryhas nostart: the hour beforeend(Jaeger requires both bounds). - DEFAULT_
TRACING_ PROTOCOL - Protocol of the Jaeger preset: OTLP over HTTP/protobuf (works through proxies).
- DEFAULT_
URL - Query endpoint (UI and HTTP query API, port 16686) used when neither the builder nor the environment sets one.
Functions§
- init_
tracing - Sets up OpenTelemetry tracing for Jaeger (SPEC §5): the environment fills every field the
config leaves unset (see
tracing_config_from_env), the exporter isjaeger_exporter.OTEL_TRACES_SAMPLER=jaeger_remote(orparentbased_jaeger_remote) turns on remote sampling with the URL fromOTEL_TRACES_SAMPLER_ARGendpoint=, elseGROW_JAEGER_SAMPLING_URL/JAEGER_SAMPLING_ENDPOINT/ the default. Must be called inside a tokio runtime. CallJaegerTracingHandle::shutdownbefore exit. - init_
tracing_ with_ options init_tracingwith options.- init_
tracing_ with_ remote_ sampler init_tracingwith aJaegerRemoteSamplerdeciding sampling (parent-based; the sampler is not closed by the handle).- jaeger_
exporter - Builds the official OTLP span exporter for Jaeger from a config (the exporter factory of
init_tracing_with):http/protobufposts protobuf to the resolved endpoint (seeresolve_endpoint),grpcuses tonic. Headers, compression, timeout and TLS (CA, client certificate,insecure_skip_verifyover HTTP) come from the config.nativeisCONFIG(Jaeger ingests OTLP), and so isinsecure_skip_verifyover gRPC (tonic cannot skip verification). The environment is not read here; seetracing_config_from_env. - parse_
sampling_ strategy - Parses and validates a
/samplingresponse body. Missing numbers count as 0 (proto3 JSON omits zero values); a missingstrategyTypemeansPROBABILISTIC; aRATE_LIMITINGstrategy withoutrateLimitingSamplingorprobabilisticSamplingrate-limits at 0 traces per second.VALIDATIONfor malformed JSON, an unknown type or values out of range. - resolve_
endpoint - The exporter URL for a protocol: for
http/protobuf, an endpoint without a path (a base such ashttp://jaeger:4318) gets/v1/traces; any other endpoint is used as is. Without an endpoint, the Jaeger default for the protocol. - tracing_
config_ from_ env - Fills every unset field of
configfromenvand applies the Jaeger preset (protocolhttp/protobuf, endpoint per protocol, always set in the result). Precedence: explicit >GROW_JAEGER_OTLP_*>OTEL_EXPORTER_OTLP_TRACES_*>OTEL_EXPORTER_OTLP_*> default. A field still at itsTracingConfig::newdefault counts as unset.
Type Aliases§
- Jaeger
Error - Service-prefixed alias of
Error.