Skip to content

Client functions

JaegerClient talks to the Jaeger query service (port 16686) and is the entry point to the other modules: query (Trace queries), initTracing (Tracing setup) and remoteSampler / samplingStrategy (Remote sampling). Create one per process and close it on shutdown: close() is idempotent and also shuts down every tracing handle and remote sampler created through the client. The shared behaviour (timeouts, retries, hooks, errors) is described in Client.

health

GET / on the query port (the stack catalog health target), without the token. With healthUrl set (healthcheckv2, port 13133, /status), its answer is added to details with the prefix healthcheck.; an unhealthy answer there gives healthy=false, status="degraded". Never throws for an unhealthy or unreachable service (status="unreachable"), only for CANCELLED and CONFIG.

const health = await client.health();
if (!health.healthy) console.warn(health.status, health.details);
let health = client.health().await?;
println!("{} {}", health.healthy, health.status);
hs, err := client.Health(ctx)
if err == nil && !hs.Healthy {
    log.Printf("jaeger %s %v", hs.Status, hs.Details)
}
health = client.health()
print(health.healthy, health.status, health.details)
HealthStatus health = client.health();
System.out.println(health.healthy() + " " + health.status());

ping

Authenticated round trip through the query API (GET /api/v3/services); returns the latency. Raises AuthenticationError when an auth proxy rejects the token.

const latencyMs = await client.ping();
let latency: std::time::Duration = client.ping().await?;
latency, err := client.Ping(ctx)
latency_ms = client.ping()
Duration latency = client.ping();

serverVersion / buildInfo

serverVersion() returns the version without the leading v (2.23.0): from JAEGER_VERSION in the UI page (GET /), else from target_info{service_version=…} at metricsUrl (port 8888). It raises UnsupportedError when neither source reports one; a 404 from either source means "no version", not NotFoundError. buildInfo() returns the whole JAEGER_VERSION object (gitVersion, gitCommit, buildDate) or null.

const version = await client.serverVersion();   // "2.23.0"
const info = await client.buildInfo();          // { gitVersion: "v2.23.0", gitCommit, buildDate } | null
let version = client.server_version().await?;
if let Some(info) = client.build_info().await? {
    println!("{:?} {:?}", info.git_version, info.git_commit);
}
version, err := client.ServerVersion(ctx)   // errors.Is(err, jaeger.ErrUnsupported)
info, err := client.BuildInfo(ctx)           // *jaeger.BuildInfo or nil
version = client.server_version()
info = client.build_info()   # {"gitVersion": "v2.23.0", ...} or None
String version = client.serverVersion();
Optional<JaegerBuildInfo> info = client.buildInfo();

samplingStrategy

Fetches the remote sampling strategy of a service once: GET {samplingUrl}?service=<name>, with the client's settings and token. A blank service raises ValidationError without a request. See Remote sampling for the strategy model.

const strategy = await client.samplingStrategy("checkout");
console.log(strategy.type, strategy.samplingRate, strategy.operations);
let strategy = client.sampling_strategy("checkout").await?;
println!("{:?} {}", strategy.strategy_type, strategy.sampling_rate);
strategy, err := client.SamplingStrategy(ctx, "checkout")
fmt.Println(strategy.StrategyType, strategy.SamplingRate)
strategy = client.sampling_strategy("checkout")
print(strategy.type, strategy.sampling_rate)
JaegerSamplingStrategy strategy = client.samplingStrategy("checkout");
System.out.println(strategy.samplingRate());

initTracing (client)

The same as the package-level initTracing, but a remote sampler started for OTEL_TRACES_SAMPLER=jaeger_remote (or requested in code) uses the client's configuration (samplingUrl, token, TLS), and close() shuts the handle down (flushing its spans).

const handle = client.initTracing({ serviceName: "checkout" });
use grow_jaeger::{tracing::TracingConfig, JaegerTracingOptions};

let handle = client.init_tracing(TracingConfig::new("checkout"), JaegerTracingOptions::default())?;
h, err := client.InitTracing(ctx, jaeger.TracingConfig{ServiceName: "checkout"})
handle = client.init_tracing(service_name="checkout")
JaegerTracingHandle handle = client.initTracing(TracingConfig.builder("checkout").build());

remoteSampler

A started JaegerRemoteSampler for a service that uses the client's settings (samplingUrl, timeouts, TLS, proxy, headers, token). close() stops it.

const sampler = client.remoteSampler({ serviceName: "checkout", pollIntervalMs: 60_000 });
let sampler = client.remote_sampler("checkout", Duration::from_secs(60))?;
sampler, err := client.NewRemoteSampler("checkout", time.Minute)
sampler = client.remote_sampler("checkout", 60)
JaegerRemoteSampler sampler = client.remoteSampler("checkout", Duration.ofMinutes(1));

close

Idempotent. Shuts down the tracing handles (flushing their batch processors) and the samplers created through the client, then releases connections. Later calls fail with CANCELLED ("<operation>: client is closed"); only Python's init_tracing and remote_sampler raise CONFIG on a closed client.

await client.close();
client.close().await;
defer client.Close()
with JaegerClient.from_env() as client:   # or client.close(); async: await client.aclose()
    ...
try (JaegerClient client = JaegerClient.fromEnv()) {
    // ...
}