log_io/
lib.rs

1//! Structured logging pipeline for Rust.
2//!
3//! `log-io` is an IO pipeline for structured log records. It is not a
4//! wrapper around `log` or `tracing`. A record flows through a small
5//! number of well-defined stages: filter, format, sink. Each stage is
6//! independently composable.
7//!
8//! # Quick start
9//!
10//! ```no_run
11//! use log_io::{Field, Level, Logger, Value};
12//!
13//! let logger = Logger::builder()
14//!     .level(Level::Info)
15//!     .stdout_json()
16//!     .build();
17//!
18//! logger.log(
19//!     Level::Info,
20//!     "server started",
21//!     &[Field::new("port", Value::U64(8080))],
22//! );
23//! ```
24//!
25//! # Features
26//!
27//! * `std` (default): enables IO sinks, file output, async-safe locks,
28//!   thread-local context propagation, and timestamps. When disabled,
29//!   the crate compiles in `no_std` mode with only the data model and
30//!   [`core::fmt::Write`]-based formatters available.
31//! * `json` (default): JSON output format.
32//! * `logfmt` (default): `key=value` logfmt output format.
33//! * `human` (default): human-readable format with aligned columns
34//!   and RFC 3339 timestamps. `no_std`-compatible.
35//!
36//! # Design notes
37//!
38//! The fast path is allocation-free in steady state. [`Record`],
39//! [`Field`], and [`Value`] all borrow their data. Formatters
40//! serialize directly into a writer; the built-in sinks use a
41//! thread-local scratch buffer so per-record formatting does not
42//! touch the allocator after the first call.
43//!
44//! # Stability
45//!
46//! `1.x.y` releases preserve backwards compatibility. The full public
47//! API surface is documented in `REPS.md` section 4 and exhaustively
48//! in `docs/API.md`.
49
50#![doc(html_root_url = "https://docs.rs/log-io")]
51#![cfg_attr(docsrs, feature(doc_cfg))]
52#![cfg_attr(not(feature = "std"), no_std)]
53#![forbid(unsafe_code)]
54#![warn(missing_docs)]
55#![warn(clippy::all)]
56
57/// Crate version string, populated by Cargo at build time.
58pub const VERSION: &str = env!("CARGO_PKG_VERSION");
59
60mod level;
61mod record;
62mod value;
63
64pub use crate::level::{Level, ParseLevelError};
65pub use crate::record::{Field, Metadata, Record};
66pub use crate::value::Value;
67
68#[cfg(feature = "std")]
69mod filter;
70#[cfg(feature = "std")]
71pub use crate::filter::{Filter, FilterRule, ParseFilterError};
72
73pub mod format;
74pub use crate::format::Format;
75
76#[cfg(feature = "std")]
77mod error;
78#[cfg(feature = "std")]
79pub use crate::error::{Error, Result};
80
81#[cfg(feature = "std")]
82pub mod sink;
83#[cfg(feature = "std")]
84pub use crate::sink::Sink;
85
86#[cfg(feature = "std")]
87mod logger;
88#[cfg(feature = "std")]
89pub use crate::logger::{Logger, LoggerBuilder};
90
91#[cfg(feature = "std")]
92pub mod context;
93
94#[cfg(feature = "std")]
95pub(crate) mod time;
96
97#[cfg(feature = "std")]
98mod macros;
log_io/lib.rs

log_io/
lib.rs
