kamu_logging/
lib.rs

1//! `kamu-logging` — opinionated `tracing` setup for PT IMMER services.
2//!
3//! Call [`init`] from `main` for the zero-config path, or [`init_with`] with
4//! an [`InitOptions`] builder for explicit format / sink / filter / OTLP
5//! configuration. See the crate README for worked examples.
6//! On `wasm32-unknown-unknown`, enable only the `wasm32` feature to install a
7//! panic hook and emit `tracing` events to the JavaScript console. This path is
8//! suitable for Cloudflare Workers via `workers-rs`; systemd, Actix Web, and
9//! OTLP exporter features are native-only.
10//!
11//! Re-exports common `tracing` items so consumers can avoid a separate
12//! `tracing` import for the basic logging vocabulary.
13
14#![deny(missing_docs)]
15
16#[cfg(all(feature = "systemd", feature = "wasm32"))]
17compile_error!("Feature \"systemd\" can't be combined with \"wasm32\".");
18
19#[cfg(all(feature = "with-actix-web", feature = "wasm32"))]
20compile_error!("Feature \"with-actix-web\" can't be combined with \"wasm32\".");
21
22#[cfg(all(feature = "with-otlp", feature = "wasm32"))]
23compile_error!("Feature \"with-otlp\" can't be combined with \"wasm32\".");
24
25#[cfg(not(any(feature = "systemd", feature = "wasm32")))]
26compile_error!("At least feature \"systemd\" or \"wasm32\" must be enabled.");
27
28pub mod correlation;
29
30mod init;
31mod options;
32
33#[cfg(feature = "with-actix-web")]
34mod actix;
35
36#[cfg(feature = "with-otlp")]
37pub mod otlp;
38
39pub use crate::init::{init, init_or_skip, init_with};
40pub use crate::options::{Format, InitOptions, Sink};
41
42#[cfg(feature = "with-actix-web")]
43pub use crate::actix::{EnrichedRootSpanBuilder, get_actix_web_logger, get_actix_web_logger_with};
44
45#[cfg(feature = "with-otlp")]
46pub use crate::otlp::{SpanProcessorMode, flush_otlp, shutdown_otlp};
47
48/// Re-exports of the common `tracing` vocabulary so consumers can
49/// `use kamu_logging::{info, instrument, ...}` without a separate import.
50pub use tracing::{Level, Span, debug, enabled, error, event, info, instrument, span, trace, warn};
51
52/// Errors returned by [`init`] / [`init_with`].
53///
54/// Marked `#[non_exhaustive]` so future variants are not breaking changes.
55#[non_exhaustive]
56#[derive(thiserror::Error, Debug)]
57pub enum Error {
58    /// I/O failure during subscriber setup (typically the journald socket).
59    #[error("{0}")]
60    IO(#[from] std::io::Error),
61
62    /// A subscriber is already set and `idempotent` was `false`.
63    #[error("logging subscriber already initialized")]
64    AlreadyInitialized,
65
66    /// The requested options are not supported on the selected target.
67    #[error("invalid logging configuration: {0}")]
68    InvalidConfiguration(String),
69
70    /// `tracing::subscriber::set_global_default` failed.
71    #[error("{0}")]
72    TracingGlobal(#[from] tracing::subscriber::SetGlobalDefaultError),
73
74    /// `log::set_logger` failed (the `log` → `tracing` bridge).
75    #[cfg(feature = "systemd")]
76    #[error("{0}")]
77    TracingLog(#[from] tracing_log::log::SetLoggerError),
78
79    /// OTLP exporter construction failed.
80    #[cfg(feature = "with-otlp")]
81    #[error("OTLP init failed: {0}")]
82    OtlpInit(String),
83}
kamu_logging/lib.rs

kamu_logging/
lib.rs
