Crate telemetry_init 

One-call observability bootstrap for Rust services.

telemetry-init replaces the estate’s hand-wired tracing_subscriber + otelkit + metrics-kit init blocks (~40–80 lines each, six dialects) with a single fallible call that wires, in estate-default shape:

• Logs — tracing_subscriber with an EnvFilter (the configured directive, overridden by RUST_LOG) and a fmt layer: single-line JSON by default, human format for local dev.
• Metrics — a lock-free metrics_kit::Registry with a cardinality budget, handed to you as an Arc so hot-path handles register through it (feature metrics, default on).
• Traces — an opentelemetry-otlp exporter wired as a tracing-opentelemetry layer with service.name/service.version resource attributes and parent-based ratio sampling (feature otlp, default off).

Design

• One init, typed failure. Telemetry::init returns TelemetryError; double-initialization — the global subscriber is a once-per-process resource — is TelemetryError::AlreadyInitialized, never a panic.
• No hidden globals for metrics. The registry is returned to the caller as an Arc (the metrics-kit pattern). Only the tracing subscriber is global, because that is tracing’s own design.
• Explicit shutdown, best-effort drop. Telemetry::shutdown is the guaranteed flush path and idempotent; Drop does a best-effort flush in case teardown is forgotten.
• No silent fallbacks. Requesting LogFormat::Json without the json feature is a configuration error, not quiet plain text.

Example

use telemetry_init::{LogFormat, Telemetry, TelemetryConfig};

let telemetry = Telemetry::init(
    TelemetryConfig::new("payments-api")
        .version(env!("CARGO_PKG_VERSION"))
        .log_format(LogFormat::Pretty)
        .log_level("info"),
)?;

tracing::info!("service started");

telemetry.shutdown()?;

Metrics

With the default metrics feature, Telemetry::metrics hands back the registry for hot-path registration:

use telemetry_init::{Telemetry, TelemetryConfig};

let telemetry = Telemetry::init(
    TelemetryConfig::new("payments-api").metrics_budget(4096),
)?;

let requests = telemetry
    .metrics()
    .counter("http_requests_total", "Total HTTP requests.", &[])
    .expect("unique series name");
requests.inc();

assert!(telemetry.metrics().render().contains("http_requests_total 1"));
telemetry.shutdown()?;

Traces (feature otlp)

let telemetry = Telemetry::init(
    TelemetryConfig::new("payments-api")
        .otlp_endpoint("http://localhost:4317")
        .sample_rate(0.1),
)?;

Why not otelkit::init?

otelkit v2’s public API is a whole-subscriber init: otelkit::init installs its own global subscriber and returns a flush guard. It cannot compose as a layer inside this crate’s single subscriber, and its OTLP path ignores the log format and RUST_LOG. telemetry-init therefore wires opentelemetry-otlp + tracing-opentelemetry directly, keeping one code path for every feature combination.

Feature flags

Feature	Default	Description
metrics	yes	metrics-kit registry via Telemetry::metrics
json	yes	JSON log format (LogFormat::Json)
otlp	no	OTLP trace export via opentelemetry-otlp

Structs

Subscriber

A boxed Subscriber with a real Debug impl (the diagnostics matter; the subscriber’s innards do not).

Telemetry

The installed stack handed to callers: an installed global subscriber is a process-wide singleton, so the handle carries only what callers need afterwards.

TelemetryConfig

Bootstrap configuration for the estate telemetry stack.

Enums

LogFormat

Log output format for the subscriber’s fmt layer.

TelemetryError

Initialization and shutdown failures.

Constants

DEFAULT_LOG_LEVEL

Default env-filter directive when neither RUST_LOG nor an explicit log_level override applies.

DEFAULT_METRICS_BUDGET

Default series budget handed to the metrics-kit registry.

DEFAULT_SAMPLE_RATE

Default trace sample rate: record every span.

DEFAULT_SERVICE_VERSION

Default service version recorded when none is supplied.

Functions

build_subscriber

Construct the estate subscriber described by config without installing it.

effective_max_level

The effective max verbosity Telemetry::init would install for config, honoring the RUST_LOG override. Round-4 estate feedback: lets hosts verify filter configuration without installing anything.