Skip to main content

ash_log/
tracing_bridge.rs

1//! Routes [`tracing`] events into a [`Logger`].
2//!
3//! This is the supported way to capture application logging, including output
4//! from third-party crates that already use `tracing` or the `log` facade. It
5//! replaces any attempt to capture `println!`: a `tracing` event arrives with a
6//! level, a target module, a source location, and named fields, all as
7//! structured data, so the resulting record can be classified honestly and
8//! signed. Captured stdout text has none of that.
9//!
10//! # Example
11//!
12//! ```rust
13//! use ash_log::*;
14//! use std::sync::Arc;
15//! use tracing_subscriber::layer::SubscriberExt;
16//! use tracing_subscriber::util::SubscriberInitExt;
17//!
18//! let logger = Arc::new(
19//!     Logger::builder(Arc::new(StdoutAuditBackend))
20//!         .min_level(AuditSeverity::Info)
21//!         .build(),
22//! );
23//!
24//! tracing_subscriber::registry()
25//!     .with(AshLogLayer::new(logger))
26//!     .init();
27//!
28//! tracing::info!(user = "alice", "login succeeded");
29//! ```
30//!
31//! # Level mapping
32//!
33//! | `tracing` | [`AuditSeverity`] |
34//! |-----------|-------------------|
35//! | `TRACE`   | [`Trace`](AuditSeverity::Trace) |
36//! | `DEBUG`   | [`Debug`](AuditSeverity::Debug) |
37//! | `INFO`    | [`Info`](AuditSeverity::Info) |
38//! | `WARN`    | [`Warning`](AuditSeverity::Warning) |
39//! | `ERROR`   | [`Error`](AuditSeverity::Error) |
40//!
41//! `tracing` has no level above `ERROR`, so a bridged event is never
42//! [`Critical`](AuditSeverity::Critical) and is always a
43//! [`Diagnostic`](crate::AuditEventType::Diagnostic) record. Security events
44//! are logged directly through [`Logger`], never through this bridge — a
45//! diagnostic must not be able to claim a security classification it has not
46//! earned.
47
48use super::{AuditEvent, AuditSeverity, Logger, Provenance};
49use std::sync::Arc;
50use tracing::field::{Field, Visit};
51use tracing_subscriber::layer::{Context, Layer};
52
53/// Field name `tracing` uses for the formatted message of an event.
54const MESSAGE_FIELD: &str = "message";
55
56/// Translate a [`tracing::Level`] into an [`AuditSeverity`].
57fn map_level(level: tracing::Level) -> AuditSeverity {
58    match level {
59        tracing::Level::TRACE => AuditSeverity::Trace,
60        tracing::Level::DEBUG => AuditSeverity::Debug,
61        tracing::Level::INFO => AuditSeverity::Info,
62        tracing::Level::WARN => AuditSeverity::Warning,
63        tracing::Level::ERROR => AuditSeverity::Error,
64    }
65}
66
67/// Collects an event's message and its remaining fields as metadata.
68#[derive(Default)]
69struct FieldCollector {
70    message: Option<String>,
71    fields: serde_json::Map<String, serde_json::Value>,
72}
73
74impl FieldCollector {
75    /// Record one field, keeping `message` separate from the rest.
76    fn insert(&mut self, field: &Field, value: serde_json::Value) {
77        if field.name() == MESSAGE_FIELD {
78            self.message = match value {
79                serde_json::Value::String(s) => Some(s),
80                other => Some(other.to_string()),
81            };
82        } else {
83            self.fields.insert(field.name().to_string(), value);
84        }
85    }
86}
87
88impl Visit for FieldCollector {
89    fn record_str(&mut self, field: &Field, value: &str) {
90        self.insert(field, serde_json::Value::from(value));
91    }
92
93    fn record_bool(&mut self, field: &Field, value: bool) {
94        self.insert(field, serde_json::Value::from(value));
95    }
96
97    fn record_i64(&mut self, field: &Field, value: i64) {
98        self.insert(field, serde_json::Value::from(value));
99    }
100
101    fn record_u64(&mut self, field: &Field, value: u64) {
102        self.insert(field, serde_json::Value::from(value));
103    }
104
105    fn record_f64(&mut self, field: &Field, value: f64) {
106        self.insert(field, serde_json::Value::from(value));
107    }
108
109    fn record_error(&mut self, field: &Field, value: &(dyn std::error::Error + 'static)) {
110        self.insert(field, serde_json::Value::from(value.to_string()));
111    }
112
113    fn record_debug(&mut self, field: &Field, value: &dyn std::fmt::Debug) {
114        self.insert(field, serde_json::Value::from(format!("{value:?}")));
115    }
116}
117
118/// A [`tracing_subscriber`] layer that writes every event it sees to a
119/// [`Logger`] as a diagnostic record.
120///
121/// Level filtering stays with the `Logger`, so one threshold governs both
122/// directly-logged and bridged events. Use `tracing`'s own filtering as well if
123/// you want to avoid the cost of constructing events that would be dropped.
124pub struct AshLogLayer {
125    logger: Arc<Logger>,
126}
127
128impl AshLogLayer {
129    /// Bridge `tracing` events into `logger`.
130    #[must_use]
131    pub fn new(logger: Arc<Logger>) -> Self {
132        Self { logger }
133    }
134
135    /// The logger this layer writes to.
136    #[must_use]
137    pub fn logger(&self) -> &Arc<Logger> {
138        &self.logger
139    }
140}
141
142impl std::fmt::Debug for AshLogLayer {
143    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
144        f.debug_struct("AshLogLayer").finish_non_exhaustive()
145    }
146}
147
148impl<S: tracing::Subscriber> Layer<S> for AshLogLayer {
149    fn on_event(&self, event: &tracing::Event<'_>, _ctx: Context<'_, S>) {
150        let metadata = event.metadata();
151        let severity = map_level(*metadata.level());
152
153        // Skip the work of collecting fields for an event that will be dropped.
154        // Bridged events are always diagnostics, so the level decides alone.
155        if severity < self.logger.min_level() {
156            return;
157        }
158
159        let mut collector = FieldCollector::default();
160        event.record(&mut collector);
161
162        let mut provenance = Provenance::new().with_module(metadata.target());
163        if let Some(file) = metadata.file() {
164            provenance = provenance.with_file(file);
165        }
166        if let Some(line) = metadata.line() {
167            provenance = provenance.with_line(line);
168        }
169        provenance.thread = std::thread::current().name().map(ToString::to_string);
170        provenance.pid = Some(std::process::id());
171
172        let mut builder = AuditEvent::diagnostic(collector.message.unwrap_or_default())
173            .severity(severity)
174            .provenance(provenance);
175
176        for (key, value) in collector.fields {
177            builder = builder.metadata(key, value);
178        }
179
180        self.logger.log(builder.build());
181    }
182}
183
184#[cfg(test)]
185mod tests {
186    use super::*;
187    use crate::{AuditBackend, AuditEventType};
188    use std::sync::{Mutex, PoisonError};
189    use tracing_subscriber::layer::SubscriberExt as _;
190
191    #[derive(Default)]
192    struct Collector(Mutex<Vec<AuditEvent>>);
193
194    impl Collector {
195        fn events(&self) -> Vec<AuditEvent> {
196            self.0
197                .lock()
198                .unwrap_or_else(PoisonError::into_inner)
199                .clone()
200        }
201    }
202
203    impl AuditBackend for Collector {
204        fn log_audit(&self, event: &AuditEvent) {
205            self.0
206                .lock()
207                .unwrap_or_else(PoisonError::into_inner)
208                .push(event.clone());
209        }
210    }
211
212    /// Run `body` with a subscriber bridging into a fresh collector.
213    fn with_bridge<F: FnOnce()>(min_level: AuditSeverity, body: F) -> Vec<AuditEvent> {
214        let collector = Arc::new(Collector::default());
215        let logger = Arc::new(
216            Logger::builder(collector.clone())
217                .min_level(min_level)
218                .build(),
219        );
220        let subscriber = tracing_subscriber::registry().with(AshLogLayer::new(logger));
221        tracing::subscriber::with_default(subscriber, body);
222        collector.events()
223    }
224
225    #[test]
226    fn test_levels_map_across() {
227        for (level, expected) in [
228            (tracing::Level::TRACE, AuditSeverity::Trace),
229            (tracing::Level::DEBUG, AuditSeverity::Debug),
230            (tracing::Level::INFO, AuditSeverity::Info),
231            (tracing::Level::WARN, AuditSeverity::Warning),
232            (tracing::Level::ERROR, AuditSeverity::Error),
233        ] {
234            assert_eq!(map_level(level), expected);
235        }
236    }
237
238    #[test]
239    fn test_event_becomes_a_diagnostic_record() {
240        let events = with_bridge(AuditSeverity::Trace, || {
241            tracing::info!("service started");
242        });
243
244        assert_eq!(events.len(), 1);
245        assert_eq!(events[0].event_type, AuditEventType::Diagnostic);
246        assert_eq!(events[0].severity, AuditSeverity::Info);
247        assert_eq!(events[0].message.as_deref(), Some("service started"));
248    }
249
250    #[test]
251    fn test_structured_fields_become_metadata() {
252        let events = with_bridge(AuditSeverity::Trace, || {
253            tracing::warn!(user = "alice", attempts = 3, ok = false, "rate limited");
254        });
255
256        assert_eq!(events.len(), 1);
257        let event = &events[0];
258        assert_eq!(event.message.as_deref(), Some("rate limited"));
259        assert_eq!(
260            event
261                .metadata
262                .get("user")
263                .and_then(serde_json::Value::as_str),
264            Some("alice")
265        );
266        assert_eq!(
267            event
268                .metadata
269                .get("attempts")
270                .and_then(serde_json::Value::as_i64),
271            Some(3)
272        );
273        assert_eq!(
274            event
275                .metadata
276                .get("ok")
277                .and_then(serde_json::Value::as_bool),
278            Some(false)
279        );
280    }
281
282    #[test]
283    fn test_provenance_records_the_emitting_module_and_location() {
284        let events = with_bridge(AuditSeverity::Trace, || {
285            tracing::error!("disk failure");
286        });
287
288        let provenance = &events[0].provenance;
289        assert_eq!(provenance.module.as_deref(), Some(module_path!()));
290        assert_eq!(provenance.file.as_deref(), Some(file!()));
291        assert!(provenance.line.is_some());
292        assert!(provenance.pid.is_some());
293    }
294
295    #[test]
296    fn test_bridged_events_respect_the_logger_threshold() {
297        let events = with_bridge(AuditSeverity::Warning, || {
298            tracing::debug!("noise");
299            tracing::info!("also noise");
300            tracing::warn!("kept");
301            tracing::error!("also kept");
302        });
303
304        let levels: Vec<AuditSeverity> = events.iter().map(|e| e.severity).collect();
305        assert_eq!(levels, vec![AuditSeverity::Warning, AuditSeverity::Error]);
306    }
307
308    #[test]
309    fn test_bridged_events_are_never_security_relevant() {
310        // A diagnostic must not be able to claim a security classification.
311        let events = with_bridge(AuditSeverity::Trace, || {
312            tracing::error!("authentication failed");
313        });
314
315        assert!(
316            !events[0].event_type.is_security_relevant(),
317            "a bridged event must never enter the security tier"
318        );
319    }
320
321    #[test]
322    fn test_event_without_a_message_still_records() {
323        let events = with_bridge(AuditSeverity::Trace, || {
324            tracing::info!(counter = 7);
325        });
326
327        assert_eq!(events.len(), 1);
328        assert_eq!(events[0].message.as_deref(), Some(""));
329        assert_eq!(
330            events[0]
331                .metadata
332                .get("counter")
333                .and_then(serde_json::Value::as_i64),
334            Some(7)
335        );
336    }
337}