Crate obs_kit 

Façade crate — re-exports the everyday obs API.

Most downstream apps depend only on obs-kit. Spec 61 § 2.11 + boundary-review § 3.6 (init_for_service).

Phase 3 (obs-migration spec § 5):

• Re-exports obs-core’s sink and wire sub-modules by path so consumers implementing custom Sinks or walking the envelope codec don’t need a direct obs-core dep.
• Module aliases for every feature-gated sub-crate: obs_kit::{live_tail, prom, sink_batch, otel, tracing_bridge}.
• self_event / SelfEventBuilder collapse the hand-built ObsEnvelope { tier, sev, sampling_reason, ts_ns, .. } pattern into one helper.
• proto is the explicit “here be dragons” escape hatch for the rare call sites (partitioner, live-tail serializer) that need typed direct-field access on the wire envelope.

Re-exports

pub use obs_core::__private::secrecy;

pub use obs_otel as otel;

Modules

observer

Three-tier observer resolution + the Observer trait.

proto

Proto-type escape hatch for the rare call sites that need direct access to the wire envelope’s typed enum fields — partitioners dispatching on proto::Severity / proto::SamplingReason, live-tail serializers that render the proto name, sink framework tests that assert on proto::EnumValue variants. Phase 3 spec § 5.1 + § 6.4.

sink

Wire codec and sink trait sub-modules. Consumers implementing a custom Sink or reading/writing envelopes on the wire previously had to depend on obs-core directly; obs-kit re-exports these so obs-kit = "0.2" is the only runtime dep needed. Spec § 5.1. Sinks consume ScrubbedEnvelope and ship it to a destination (stdout, NDJSON file, OTLP, ClickHouse, etc.).

wire

Wire codec and sink trait sub-modules. Consumers implementing a custom Sink or reading/writing envelopes on the wire previously had to depend on obs-core directly; obs-kit re-exports these so obs-kit = "0.2" is the only runtime dep needed. Spec § 5.1. Wire-format helpers for obs.

Macros

context

obs::context!(name = value, ...) — like obs::scope! but without the per-scope tail buffer. Spec 13 § 2.2.

emit

Function-like emit macro: obs::emit!(MyEvent { field: value }) or obs::emit!(WARN, MyEvent { field: value }) to escalate.

forensic

obs::forensic!(site = "...", message = "...", { "k" => v, ... }) — emergency escape hatch. Always emits, regardless of sampling. Spec 13 § 8.

include_schemas

obs::include_schemas!("myapp.v1") — wire up every file obs-build emits into the user’s crate. Expands to four include! calls under OUT_DIR/obs/. Spec 12 § 3.1.

scope

obs::scope!(name = value, ...) — push an obs::scope! frame onto the active task’s scope stack. Returns a ScopeGuard that pops the frame on drop and flushes the tail-on-error buffer when >= ERROR was observed inside.

Structs

EventsConfig

The complete config tree. Every field is optional so a config file can be a single line if the user only cares to override filter.

FanOutSink

Multiplex a single tier’s output across N sinks.

FieldCapture

Visitor used by tracing’s Event::record(visitor) to extract typed values into a thread-local scratch space; reused across emissions (zero per-event allocation in the steady state). Spec 12 § 3.6.

FieldMeta

Compile-time field metadata emitted by codegen alongside each EventSchema impl. Mirrors the proto-side obs.v1.FieldMeta.

Filter

Parsed obs::Filter. Statics are checked first against the callsite; dynamics are bucketed by full_name and consulted at emit time against env.labels.

InMemoryHandle

Stable handle to an InMemorySink. Clone-safe; share across threads.

InMemoryObserver

Test-grade observer: every envelope is delivered to an InMemorySink. Spec 61 § 2.4 example.

InMemorySink

Test sink: collects envelopes into a bounded ring buffer.

InitBuilder

Builder returned by init_for_service. Configure the service, preset, and any per-tier sink overrides; finish with Self::install.

InitGuard

RAII guard returned by InitBuilder::install. On drop, calls the global observer’s shutdown_blocking with the configured budget so in-flight envelopes have a bounded window to flush.

Instrumented

Future adapter that re-enters an obs::scope! frame and an Arc<dyn Observer> override on every poll. Constructed via Instrument::instrument / WithObserver::with_observer.

LevelSplitWriter

Composes two writers — INFO+ goes through low, WARN+ through high. The conventional shape for cargo binaries.

NdjsonFileSink

File sink that writes envelopes as JSON lines to the underlying MakeWriter. Buffers a Mutex<ErasedWriter> per batch to avoid re-opening files for every event.

NonBlockingWriter

Wraps a MakeWriter with a background thread + bounded mpsc::SyncSender channel. Overflow drops the line and increments the dropped counter. Spec 20 § 3.5.

NoopObserver

The default observer: drops every envelope.

NoopSink

A sink that drops every envelope.

ObsBatch

ObsCallsite

Static metadata for a single emit site. Constructed by codegen via the const fn constructor — no heap allocation, no first-emit cost.

ObsEnvelope

ObsFnEntered

ObsFnExecuted

ObsForensicEvent

ObsTraceCtx

Parsed W3C trace context.

RollingFileWriter

Rolling file writer with size + time policies. Spec 20 § 3.4.

RollingFileWriterBuilder

Builder for RollingFileWriter.

SamplingConfig

Sampling config (spec 15 § 2 + spec 13 § 6).

ScopeFrame

One frame on the per-task / per-thread scope stack.

ScopeFrameBuilder

Programmatic builder for pushing an obs::scope!-shaped frame.

ScopeGuard

RAII guard returned by obs::scope! and obs::context!. Dropping pops the frame; for Scope kind frames where any >= ERROR envelope was observed, the tail buffer is flushed back through the active observer with sampling_reason = TAIL_ERROR.

ScrubbedEnvelope

Read-only view of an envelope whose payload has already been run through the per-tier scrubber. Constructed by the worker; consumed by sinks.

SelfEventBuilder

Fluent builder for runtime-style self-events.

SpanCtx

Read-only view of the active scope/span context that register_typed-style closures receive. Spec 12 § 3.6.

SpanFrame

One frame of the bridge-visible span ancestry. Borrowed; never owns span data. Spec 12 § 3.6.

SpanTrace

Captured obs::scope! ancestry. Like tracing-error::SpanTrace.

StandardObserver

Production-ready observer with reloadable config and per-tier worker pool.

StandardObserverBuilder

Builder for StandardObserver.

StderrWriter

Writes to stderr.

StdoutSink

Stdout / writer-backed sink.

StdoutWriter

Writes to stdout.

TeeWriter

Tee writer — writes to both branches.

W3cPropagator

W3C traceparent header propagator.

WorkerCounters

Per-tier counters surfaced as ObsSinkDropped self-events.

WorkerGuard

Returned alongside NonBlockingWriter; flushes + joins the bg thread on drop.

Enums

Cardinality

Classification

FieldKind

FieldRole

Codegen-derived classification of a field. Decoupled from the FieldKind enum so codegen can stamp this from the descriptor without re-parsing.

FormatterStyle

Output style for StdoutSink. See spec 20 § 3.6.

InitError

Errors from InitBuilder::install.

MetricKind

RollingPolicy

Rolling policy. Spec 20 § 3.4.

SamplingReason

ScopeField

A field declared on obs::scope! / obs::context!. Field types match the envelope projection contract: trace ids land on the typed envelope slots, labels go into env.labels. Spec 13 § 2.1.

ScopeKind

Whether a frame carries a tail-on-error buffer (Scope) or is a pure broadcast frame (Context). Spec 13 § 2.2.

ServicePreset

Built-in service presets.

Severity

Tier

Constants

DEBUG

DEBUG severity shortcut for obs::emit!.

ENVELOPE_FORMAT_VER

Wire-format version of the ObsEnvelope / ObsBatch shape.

ERROR

ERROR severity shortcut for obs::emit!.

FATAL

FATAL severity shortcut for obs::emit!.

INFO

INFO severity shortcut for obs::emit!.

TRACE

Severity ident shortcuts for use with obs::emit!. The macro form accepts either Severity::Warn or the bare WARN ident.

WARN

WARN severity shortcut for obs::emit!.

Traits

BuildableTo

Marker trait implemented by typed-builder’s “all-required-fields-set” builder state. The codegen emits a blanket impl over the parameter shape typed-builder produces, so .emit() only compiles when every required setter has been called. Spec 12 § 3.6.

Emit

Blanket trait giving every EventSchema an .emit() / .emit_at(sev) shortcut.

EnumCount

Compile-time variant count for any enum used as a LABEL field. Generated by #[derive(EnumLabel)] and consulted by lint L005 so we do not depend on nightly’s variant_count. Spec 12 § 3.6.

EventSchema

Trait implemented by every Obs* event type.

Instrument

Public extension trait — .instrument(scope!(...)) on every future owned by user code.

MakeWriter

A factory that yields one io::Write per batch. Cheap to call. Spec 20 § 3.3.

MetricEmitter

Implemented by metric sinks (OTLP metrics, Prometheus exporters). Generated EventSchema::project_metrics calls one method per MEASUREMENT field. Spec 12 § 3.6.

Observer

The global observer trait. Sealed in spirit (downstream crates implement it freely, but the SDK ships NoopObserver, InMemoryObserver, StandardObserver covering 99% of cases).

Sink

A delivery destination. Called from per-tier worker tasks, never on the emit thread.

WithObserver

Public extension trait — .with_observer(o) on a future binds an observer override that follows the future across thread migration (per-task tier; spec 11 § 3.1).

Functions

extract_w3c

Free-function form of W3cPropagator::extract. Spec 93 P1-5 requires this name in obs_core::propagator.

fresh_span_id

Generate a fresh 8-byte span id rendered as 16 lowercase hex characters.

fresh_trace_id

Generate a fresh 16-byte trace id rendered as 32 lowercase hex characters. Uses BLAKE3 over a CSPRNG-friendly seed (spec 71 randomness rule).

init_for_service

Entry point. service and version become the service.name / service.version resource attributes on every envelope.

inject_w3c

Free-function form of W3cPropagator::inject.

install_observer

Install the global observer. Called once at process start.

install_panic_hook

Install the obs panic hook. Idempotent — calling more than once is a no-op.

now_ns

Wall-clock timestamp in nanoseconds since the Unix epoch, saturated at u64::MAX.

observer

Resolve the active observer.

observer_weak

Weak handle to whatever observer() would return right now.

self_event

Build a labels-only self-event envelope with sampling_reason = SAMPLING_REASON_RUNTIME and the current wall-clock ts_ns.

status_class

Map an HTTP status code to one of 1xx..5xx, err. Spec 40 § 2.

with_observer_task

Async sibling of with_test_observer: install the observer in the per-task slot for the duration of fut. This is the version the #[obs::test] async expansion uses so that an emit on a migrated-tokio-worker-thread still resolves to the test observer (the per-thread slot would not be set on the destination worker).

with_observer_task_sync

Synchronous sibling of with_observer_task used by Instrumented<F>::poll so a single poll can bind / unbind the per-task observer without requiring an await. Spec 13 § 3.

with_observer_thread_local

Sync RAII guard. Sets the per-thread observer override; restores the previous value on drop. Do not hold across .await — see the warning in spec 11 § 3.1; use Future::with_observer (Phase 3 task 3.3) for async.

with_test_observer

Test-flavored helper. Installs the observer per-thread for the duration of f; restores on closure exit. Used by #[obs::test] (Phase 2 task 2.6) and by users that want to assert what was emitted from a synchronous block.

Attribute Macros

instrument

#[obs::instrument] — wraps a function body in an obs::scope! and emits one ObsFnExecuted event on exit (default) or two (ObsFnEntered + ObsFnExecuted) when enter = true.

Derive Macros

Event

Derive macro for the Rust-first authoring path.