Client¶
JaegerClient is the entry point. Create one per process (or per set of credentials), share
it between threads/tasks and close it on shutdown. Service functions hang off the client (see
Functions).
| Function | Returns | Notes |
|---|---|---|
constructor / create / new |
client | validates the config (CONFIG error) |
fromEnv() |
client | config from GROW_JAEGER_* and the vendor variables (JAEGER_QUERY_URL, JAEGER_SAMPLING_ENDPOINT) |
health() |
HealthStatus { healthy, status, details } |
GET / on the query port without the token, plus healthcheckv2 detail when healthUrl is set; never throws for an unhealthy or unreachable service, only for CANCELLED and CONFIG |
ping() |
latency | authenticated round trip (GET /api/v3/services); AUTHENTICATION when an auth proxy rejects the token |
serverVersion() |
version string (2.23.0) |
from the UI page, else target_info at metricsUrl; UNSUPPORTED when neither reports one |
buildInfo() |
gitVersion, gitCommit, buildDate or null |
from the UI page |
samplingStrategy(service) |
sampling strategy | one fetch from samplingUrl |
query |
JaegerQueryClient |
trace queries (Trace queries) |
initTracing(config) / remoteSampler(service, pollInterval) |
tracing handle / sampler | use the client's settings; closed by close() |
close() |
— | idempotent; flushes tracing handles, stops samplers created through the client |
status is ok, degraded (healthcheckv2 reports a problem), unhealthy, unreachable (network
error) or the vendor's word. Every function with an example per language: Client functions.
Create, use and close¶
import { JaegerClient, JaegerConfig } from "@grow-codes/jaeger";
const client = new JaegerClient(new JaegerConfig({ url: "http://127.0.0.1:16686" }));
const health = await client.health(); // { healthy, status, details }
const latencyMs = await client.ping(); // number (ms)
const version = await client.serverVersion(); // string
await client.close(); // safe to call twice
// Cancellation and per-call deadline: every I/O method accepts { signal }
const status = await client.health({ signal: AbortSignal.timeout(2_000) });
use grow_jaeger::{JaegerClient, JaegerConfig};
let config = JaegerConfig::builder().url("http://127.0.0.1:16686").build()?;
let client = JaegerClient::new(config)?;
let health = client.health().await?; // HealthStatus
let latency = client.ping().await?; // Duration
let version = client.server_version().await?; // String
client.close().await; // safe to call twice
// Cancellation: drop the future, e.g. with a deadline
let status = tokio::time::timeout(std::time::Duration::from_secs(2), client.health()).await;
Without an async runtime, enable the blocking feature:
client, err := jaeger.NewClient(jaeger.Config{
CommonConfig: jaeger.CommonConfig{URL: "http://127.0.0.1:16686"},
})
if err != nil {
return err
}
defer client.Close() // safe to call twice
health, err := client.Health(ctx) // HealthStatus
latency, err := client.Ping(ctx) // time.Duration
version, err := client.ServerVersion(ctx) // string
// Cancellation and deadlines come from ctx
ctx2, cancel := context.WithTimeout(ctx, 2*time.Second)
defer cancel()
health, err = client.Health(ctx2)
from grow_jaeger import CancelToken, JaegerClient, JaegerConfig
with JaegerClient(JaegerConfig(url="http://127.0.0.1:16686")) as client:
health = client.health() # HealthStatus
latency_ms = client.ping() # float (ms)
version = client.server_version() # str
# Cancel from another thread
token = CancelToken()
health = client.health(cancel=token)
# close() ran; calling it again is safe
AsyncJaegerClient has the same methods as coroutines (await client.health(),
await client.aclose(), async with), and honours task cancellation.
JaegerConfig config = JaegerConfig.builder().url("http://127.0.0.1:16686").build();
try (JaegerClient client = JaegerClient.create(config)) {
HealthStatus health = client.health();
Duration latency = client.ping();
String version = client.serverVersion();
// Async variants return CompletableFuture; cancel(true) cancels the request
CompletableFuture<HealthStatus> pending = client.healthAsync();
pending.orTimeout(2, TimeUnit.SECONDS).join();
} // close() is idempotent
Lifecycle rules¶
- The client is safe for concurrent use. Reuse it: it keeps a connection pool.
close()flushes queued work (for example log batches) within the configured deadline and is safe to call more than once. Any call on a closed client fails withCANCELLED("<operation>: client is closed").- Each language also offers its idiomatic scope: TypeScript
try/finally, Rustclose().await(plus best-effortDrop), Godefer client.Close(), Pythonwith/async with, Java try-with-resources.