obs_kit/
lib.rs

1#![forbid(unsafe_code)]
2#![warn(rust_2024_compatibility, missing_docs, missing_debug_implementations)]
3#![cfg_attr(
4    test,
5    allow(
6        clippy::unwrap_used,
7        clippy::expect_used,
8        clippy::panic,
9        clippy::indexing_slicing
10    )
11)]
12
13//! Façade crate — re-exports the everyday obs API.
14//!
15//! Most downstream apps depend only on `obs-kit`. Spec 61 § 2.11 +
16//! boundary-review § 3.6 (`init_for_service`).
17//!
18//! Phase 3 (obs-migration spec § 5):
19//!
20//! - Re-exports `obs-core`'s `sink` and `wire` sub-modules by path so consumers implementing custom
21//!   `Sink`s or walking the envelope codec don't need a direct `obs-core` dep.
22//! - Module aliases for every feature-gated sub-crate: `obs_kit::{live_tail, prom, sink_batch,
23//!   otel, tracing_bridge}`.
24//! - [`self_event`] / [`SelfEventBuilder`] collapse the hand-built `ObsEnvelope { tier, sev,
25//!   sampling_reason, ts_ns, .. }` pattern into one helper.
26//! - [`proto`] is the explicit "here be dragons" escape hatch for the rare call sites (partitioner,
27//!   live-tail serializer) that need typed direct-field access on the wire envelope.
28
29mod init;
30mod self_event_builder;
31
32pub use init::{InitBuilder, InitError, InitGuard, ServicePreset, init_for_service};
33/// Typed wrappers for `Classification::Secret` fields. Decision D6-2:
34/// SECRET-classified event fields should be declared as
35/// `secrecy::SecretString` / `secrecy::SecretBox<T>` so the in-memory
36/// value is also redacted at `Debug` time. The runtime scrubber (spec
37/// 14 § 5) then redacts the encoded bytes before any sink sees them.
38pub use obs_core::__private::secrecy;
39#[cfg(feature = "dev")]
40pub use obs_core::sink::FormatterStyle;
41pub use obs_core::{
42    BuildableTo, Cardinality, Classification, ENVELOPE_FORMAT_VER, Emit, EnumCount, EventSchema,
43    EventsConfig, FanOutSink, FieldCapture, FieldKind, FieldMeta, FieldRole, Filter,
44    InMemoryHandle, InMemoryObserver, InMemorySink, Instrument, Instrumented, LevelSplitWriter,
45    MakeWriter, MetricEmitter, MetricKind, NdjsonFileSink, NonBlockingWriter, NoopObserver,
46    NoopSink, ObsBatch, ObsCallsite, ObsEnvelope, ObsTraceCtx, Observer, RollingFileWriter,
47    RollingFileWriterBuilder, RollingPolicy, SamplingConfig, SamplingReason, ScopeField,
48    ScopeFrame, ScopeFrameBuilder, ScopeGuard, ScopeKind, ScrubbedEnvelope, Severity, Sink,
49    SpanCtx, SpanFrame, SpanTrace, StandardObserver, StandardObserverBuilder, StderrWriter,
50    StdoutSink, StdoutWriter, TeeWriter, Tier, W3cPropagator, WithObserver, WorkerCounters,
51    WorkerGuard, extract_w3c, fresh_span_id, fresh_trace_id, inject_w3c, install_observer,
52    install_panic_hook, now_ns, observer, observer_weak, self_event, status_class,
53    with_observer_task, with_observer_task_sync, with_observer_thread_local, with_test_observer,
54};
55/// Wire codec and sink trait sub-modules. Consumers implementing a
56/// custom [`Sink`] or reading/writing envelopes on the wire previously
57/// had to depend on `obs-core` directly; obs-kit re-exports these so
58/// `obs-kit = "0.2"` is the only runtime dep needed. Spec § 5.1.
59pub use obs_core::{sink, wire};
60/// In-process live-tail subscriber registry + Sink. Enable via the
61/// `live-tail` feature. Boundary-review § 3.1.
62#[cfg(feature = "live-tail")]
63pub use obs_live_tail as live_tail;
64pub use obs_macros::{Event, context, emit, forensic, include_schemas, instrument, scope};
65/// OTLP log/metric/trace exporters. Enable via the `otel` feature.
66/// Phase 3 spec § 5.1.
67#[cfg(feature = "otel")]
68pub use obs_otel as otel;
69/// Prometheus scrape exporter. Enable via the `prom` feature.
70/// Phase 2 boundary-review § 3.2.
71#[cfg(feature = "prom")]
72pub use obs_prom as prom;
73pub use obs_proto::obs::v1::{ObsFnEntered, ObsFnExecuted, ObsForensicEvent};
74/// Generic batching sink framework (triggers + retry + spool +
75/// escalation with a pluggable `BatchBackend` trait). Enable via the
76/// `batch-sink` feature. Phase 2 boundary-review § 3.1.
77#[cfg(feature = "batch-sink")]
78pub use obs_sink_batch as sink_batch;
79/// Bridge from third-party `tracing`-crate events/spans into the obs
80/// runtime. Enable via the `tracing-bridge` feature. Phase 3 spec § 5.1.
81#[cfg(feature = "tracing-bridge")]
82pub use obs_tracing_bridge as tracing_bridge;
83pub use self_event_builder::SelfEventBuilder;
84
85/// Test ergonomics — `assert_emitted!`, `#[obs::test]`. Spec 60 § 8.
86#[cfg(feature = "test")]
87pub mod test {
88    pub use obs_core::test::*;
89    pub use obs_macros::test;
90}
91
92/// Re-exports for code generated by `#[derive(Event)]` and `obs-build`.
93/// Users do not depend on these directly.
94#[doc(hidden)]
95pub use obs_core::__private;
96/// Severity ident shortcuts for use with `obs::emit!`. The macro form
97/// accepts either `Severity::Warn` or the bare `WARN` ident.
98///
99/// Post Phase 3b (obs-types retirement) these are module-level
100/// constants rather than re-exported variants — associated
101/// constants can't ride through `pub use` in Rust, so the aliasing
102/// lives at module scope.
103/// `TRACE` severity shortcut for `obs::emit!`.
104pub const TRACE: Severity = Severity::SEVERITY_TRACE;
105/// `DEBUG` severity shortcut for `obs::emit!`.
106pub const DEBUG: Severity = Severity::SEVERITY_DEBUG;
107/// `INFO` severity shortcut for `obs::emit!`.
108pub const INFO: Severity = Severity::SEVERITY_INFO;
109/// `WARN` severity shortcut for `obs::emit!`.
110pub const WARN: Severity = Severity::SEVERITY_WARN;
111/// `ERROR` severity shortcut for `obs::emit!`.
112pub const ERROR: Severity = Severity::SEVERITY_ERROR;
113/// `FATAL` severity shortcut for `obs::emit!`.
114pub const FATAL: Severity = Severity::SEVERITY_FATAL;
115
116/// Proto-type escape hatch for the rare call sites that need direct
117/// access to the wire envelope's typed enum fields — partitioners
118/// dispatching on [`proto::Severity`] / [`proto::SamplingReason`],
119/// live-tail serializers that render the proto name, sink framework
120/// tests that assert on [`proto::EnumValue`] variants. Phase 3 spec
121/// § 5.1 + § 6.4.
122///
123/// 99 % of consumers don't need this module — they use [`self_event`]
124/// / [`SelfEventBuilder`] for envelope construction and the façade
125/// [`Severity`] / [`Tier`] for enum dispatch. Reach in here when the
126/// façade surface doesn't cover your case; prefer contributing a
127/// helper back to the façade over normalising direct usage.
128pub mod proto {
129    pub use buffa::{EnumValue, Enumeration, SizeCache};
130    pub use obs_proto::obs::v1::{ObsBatch, ObsEnvelope, SamplingReason, Severity, Tier};
131}
obs_kit/lib.rs

obs_kit/
lib.rs
