loxide/lib.rs
1//! # loxide
2//!
3//! A fast, **dependency-free** structured logging library for Rust.
4//!
5//! loxide gives applications leveled, structured logs with two rendering modes —
6//! a colored human-readable format for the console and compact JSON for log
7//! aggregators — plus scoped sub-loggers, automatic redaction of sensitive
8//! fields, and ergonomic macros. It has **no third-party dependencies**: its own
9//! JSON value type ([`JsonValue`]) and UTC time handling ([`time`]) are built on
10//! `std` alone, so it compiles fast and adds nothing to your dependency tree.
11//!
12//! ## Quick start
13//!
14//! ```
15//! use loxide::{Config, Level, Logger, json, log_info};
16//!
17//! // Build a logger. `Config::from_env()` is the usual choice in real apps.
18//! let logger = Logger::new(Config::default().with_level(Level::Debug));
19//!
20//! // Method style: pass fields as `(name, JsonValue)` pairs.
21//! logger.info("server started", &[("port", json!(8080)), ("tls", json!(true))]);
22//!
23//! // Macro style: `key => value` fields, with automatic caller capture.
24//! log_info!(logger, "user logged in", "user" => "ada", "attempt" => 1);
25//! ```
26//!
27//! ## Output formats
28//!
29//! With [`Format::Auto`] (the default) loxide renders [`Format::Pretty`] when
30//! stderr is a terminal and [`Format::Json`] otherwise, so you get readable logs
31//! in development and machine-parseable logs in production automatically.
32//!
33//! - **Pretty:** `2026/07/12 10:11:12 UTC INF server started port=8080 tls=true`
34//! - **JSON:** `{"time":"2026-07-12T10:11:12Z","level":"info","message":"server started","port":8080,"tls":true}`
35//!
36//! ## Sub-loggers
37//!
38//! Attach context once and have it appear on every subsequent record:
39//!
40//! ```
41//! use loxide::{Config, Logger, json};
42//!
43//! let logger = Logger::new(Config::default());
44//! let request = logger.with_component("api").with_request_id("req-7");
45//! request.info("handling", &[("path", json!("/health"))]);
46//! // => ... component=api request_id=req-7 path=/health
47//! ```
48//!
49//! ## Redaction
50//!
51//! Fields whose key looks sensitive (`password`, `api_key`, `authorization`, …)
52//! are masked automatically in **both** formats — see the [`redact`] module.
53//!
54//! ## Configuration via the environment
55//!
56//! [`Config::from_env`] reads `LOG_LEVEL`, `LOG_FORMAT`, `LOG_CALLER`,
57//! `NO_COLOR`, and `TERM`.
58//!
59//! ## Convenience helpers
60//!
61//! The [`helpers`] module offers ready-made loggers for common events such as
62//! [`log_request`], [`log_response`], and [`log_db_query`].
63
64#![doc(html_root_url = "https://docs.rs/loxide")]
65#![forbid(unsafe_code)]
66
67pub mod config;
68pub mod helpers;
69pub mod json;
70pub mod logger;
71pub mod redact;
72pub mod time;
73
74/// Optional bridge to the [`log`](https://docs.rs/log) crate.
75/// Enabled with the `log` feature flag.
76#[cfg(feature = "log")]
77pub mod log_compat;
78
79/// Optional bridge to the [`tracing`](https://docs.rs/tracing) ecosystem.
80/// Enabled with the `tracing` feature flag.
81#[cfg(feature = "tracing")]
82pub mod tracing_compat;
83
84mod macros;
85mod pretty;
86
87pub use config::{Config, Format, Level, ParseFormatError, ParseLevelError, WriterKind};
88pub use helpers::{log_db_query, log_request, log_response, log_service_debug, log_service_error};
89pub use json::{JsonNumber, JsonValue};
90pub use logger::Logger;
91pub use redact::{is_sensitive_key, redact_map, redact_value};
92
93/// The most commonly used items, re-exported for a single glob import.
94///
95/// ```
96/// use loxide::prelude::*;
97///
98/// let logger = Logger::new(Config::default());
99/// log_info!(logger, "ready", "component" => "boot");
100/// ```
101pub mod prelude {
102 pub use crate::{Config, Format, JsonValue, Level, Logger};
103 pub use crate::{
104 json, log_debug, log_error, log_fatal, log_info, log_success, log_trace, log_warn,
105 };
106}