Skip to main content

astrs_node_api/node/
logging.rs

1//! Node logging (blueprint §9.1's `log_{error..trace} / log_with_fields`).
2//!
3//! A node's logs go two places at once, and both matter:
4//!
5//! * **Over the wire**, as `kind = Log` frames carrying an
6//!   [`astrs_wire::LogRecord`], so `astrs logs` and the TUI see them
7//!   interleaved with every other node's by HLC order (§13).
8//! * **Into `tracing`**, so a node that already instruments itself with
9//!   `tracing` keeps its local subscriber, its spans, and its `RUST_LOG`.
10//!
11//! Sending only over the wire would make a node undebuggable without a
12//! daemon; emitting only locally would make a dataflow undebuggable without
13//! ssh. Doing both costs one extra macro call per record.
14//!
15//! # Stamping
16//!
17//! Every record carries this node's HLC reading, its node id and its dataflow
18//! id before it leaves. That is what lets the merger in `astrs-log` order
19//! records from machines whose wall clocks disagree.
20//!
21//! # A dropped log is not an error
22//!
23//! Logging must never take a node down, and a node that cannot log is usually
24//! a node whose daemon has already gone. The `log_*` methods therefore return
25//! `()`; [`Node::try_log`] is there for the rare caller that wants to know.
26
27use std::collections::BTreeMap;
28
29use astrs_wire::{LogLevel, LogRecord};
30
31use crate::error::Result;
32use crate::node::Node;
33use crate::session::Outgoing;
34
35impl Node {
36    /// Emits a record at `level`.
37    ///
38    /// Never fails: see the module documentation.
39    pub fn log(&self, level: LogLevel, message: impl Into<String>) {
40        let _ = self.try_log(level, message, BTreeMap::new());
41    }
42
43    /// Emits a record at `level` with structured fields (§9.1
44    /// `log_with_fields`).
45    pub fn log_with_fields(
46        &self,
47        level: LogLevel,
48        message: impl Into<String>,
49        fields: BTreeMap<String, String>,
50    ) {
51        let _ = self.try_log(level, message, fields);
52    }
53
54    /// Emits an `ERROR` record.
55    pub fn log_error(&self, message: impl Into<String>) {
56        self.log(LogLevel::Error, message);
57    }
58
59    /// Emits a `WARN` record.
60    pub fn log_warn(&self, message: impl Into<String>) {
61        self.log(LogLevel::Warn, message);
62    }
63
64    /// Emits an `INFO` record.
65    pub fn log_info(&self, message: impl Into<String>) {
66        self.log(LogLevel::Info, message);
67    }
68
69    /// Emits a `DEBUG` record.
70    pub fn log_debug(&self, message: impl Into<String>) {
71        self.log(LogLevel::Debug, message);
72    }
73
74    /// Emits a `TRACE` record.
75    pub fn log_trace(&self, message: impl Into<String>) {
76        self.log(LogLevel::Trace, message);
77    }
78
79    /// Emits a record, reporting whether it reached the wire.
80    ///
81    /// The local `tracing` emission happens either way — a node whose daemon
82    /// has gone still deserves its own logs.
83    ///
84    /// # Errors
85    ///
86    /// [`crate::NodeError::DaemonGone`] once the session has ended, and
87    /// [`crate::NodeError::Backpressure`] when the writer is behind.
88    pub fn try_log(
89        &self,
90        level: LogLevel,
91        message: impl Into<String>,
92        fields: BTreeMap<String, String>,
93    ) -> Result<()> {
94        let message = message.into();
95        emit_locally(level, self.id().as_str(), &message, &fields);
96
97        let mut record = LogRecord::new(self.hlc_now(), level, message)
98            .with_node(self.id().clone())
99            .with_dataflow(self.dataflow_id())
100            .with_target(self.id().as_str());
101        for (key, value) in fields {
102            record = record.with_field(key, value)?;
103        }
104        let session = self.session();
105        session.try_send(Outgoing::log(session.log_subscription, record))
106    }
107
108    /// Builds a record stamped with this node's identity, without sending it.
109    ///
110    /// For a caller that wants to batch, filter or record locally before the
111    /// wire sees anything.
112    #[must_use]
113    pub fn log_record(&self, level: LogLevel, message: impl Into<String>) -> LogRecord {
114        LogRecord::new(self.hlc_now(), level, message)
115            .with_node(self.id().clone())
116            .with_dataflow(self.dataflow_id())
117            .with_target(self.id().as_str())
118    }
119
120    /// Sends an already-built record.
121    ///
122    /// # Errors
123    ///
124    /// As [`Node::try_log`].
125    pub fn send_log(&self, record: LogRecord) -> Result<()> {
126        let session = self.session();
127        session.try_send(Outgoing::log(session.log_subscription, record))
128    }
129}
130
131/// Mirrors a record into the process's own `tracing` subscriber.
132///
133/// The level has to be a compile-time constant for `tracing`'s macros, which
134/// is why this is a match rather than a single call.
135fn emit_locally(level: LogLevel, node: &str, message: &str, fields: &BTreeMap<String, String>) {
136    // `fields` is rendered rather than expanded: `tracing`'s field set is
137    // fixed at the call site, and a node's field names are not.
138    let rendered = if fields.is_empty() {
139        String::new()
140    } else {
141        fields
142            .iter()
143            .map(|(key, value)| format!("{key}={value}"))
144            .collect::<Vec<_>>()
145            .join(" ")
146    };
147    match level {
148        LogLevel::Error => tracing::error!(node, fields = %rendered, "{message}"),
149        LogLevel::Warn => tracing::warn!(node, fields = %rendered, "{message}"),
150        LogLevel::Info => tracing::info!(node, fields = %rendered, "{message}"),
151        LogLevel::Debug => tracing::debug!(node, fields = %rendered, "{message}"),
152        // `LogLevel` is `#[non_exhaustive]`; anything finer than debug is
153        // trace as far as a local subscriber is concerned.
154        _ => tracing::trace!(node, fields = %rendered, "{message}"),
155    }
156}
157
158#[cfg(test)]
159mod tests {
160    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
161
162    use super::*;
163    use crate::testing::TestHarness;
164    use std::time::Duration;
165
166    fn wait_for_logs(harness: &TestHarness, count: usize) -> Vec<LogRecord> {
167        for _ in 0..200 {
168            let logs = harness.daemon.logs();
169            if logs.len() >= count {
170                return logs;
171            }
172            std::thread::sleep(Duration::from_millis(10));
173        }
174        harness.daemon.logs()
175    }
176
177    #[test]
178    fn every_level_reaches_the_daemon() {
179        let harness = TestHarness::start().unwrap();
180        harness.node.log_error("boom");
181        harness.node.log_warn("careful");
182        harness.node.log_info("hello");
183        harness.node.log_debug("details");
184        harness.node.log_trace("everything");
185
186        let logs = wait_for_logs(&harness, 5);
187        assert_eq!(logs.len(), 5, "{logs:?}");
188        let levels: Vec<LogLevel> = logs.iter().map(|record| record.level).collect();
189        assert_eq!(
190            levels,
191            vec![
192                LogLevel::Error,
193                LogLevel::Warn,
194                LogLevel::Info,
195                LogLevel::Debug,
196                LogLevel::Trace
197            ]
198        );
199        assert_eq!(logs[0].message, "boom");
200    }
201
202    #[test]
203    fn records_carry_the_nodes_identity_and_clock() {
204        let harness = TestHarness::start().unwrap();
205        harness.node.log_info("stamped");
206        let logs = wait_for_logs(&harness, 1);
207        let record = logs.first().unwrap();
208        assert_eq!(
209            record.node.as_ref().map(astrs_wire::NodeId::as_str),
210            Some(TestHarness::DEFAULT_NODE)
211        );
212        assert_eq!(record.dataflow, Some(harness.daemon.dataflow()));
213        assert_eq!(record.target, TestHarness::DEFAULT_NODE);
214        assert!(record.timestamp > astrs_time::HlcTimestamp::EPOCH);
215    }
216
217    #[test]
218    fn structured_fields_survive_the_wire() {
219        let harness = TestHarness::start().unwrap();
220        let mut fields = BTreeMap::new();
221        let _ = fields.insert("frame".to_owned(), "42".to_owned());
222        let _ = fields.insert("camera".to_owned(), "front".to_owned());
223        harness
224            .node
225            .log_with_fields(LogLevel::Warn, "dropped a frame", fields);
226
227        let logs = wait_for_logs(&harness, 1);
228        let record = logs.first().unwrap();
229        assert_eq!(record.field("frame"), Some("42"));
230        assert_eq!(record.field("camera"), Some("front"));
231    }
232
233    #[test]
234    fn a_prebuilt_record_can_be_sent_as_is() {
235        let harness = TestHarness::start().unwrap();
236        let record = harness.node.log_record(LogLevel::Info, "prebuilt");
237        assert_eq!(record.message, "prebuilt");
238        harness.node.send_log(record).unwrap();
239        let logs = wait_for_logs(&harness, 1);
240        assert_eq!(
241            logs.first().map(|record| record.message.clone()),
242            Some("prebuilt".to_owned())
243        );
244    }
245
246    #[test]
247    fn logging_after_shutdown_is_reported_but_not_fatal() {
248        let mut harness = TestHarness::start().unwrap();
249        harness.node.shutdown().unwrap();
250        // The infallible face stays infallible.
251        harness.node.log_error("after the end");
252        let error = harness
253            .node
254            .try_log(LogLevel::Info, "after the end", BTreeMap::new())
255            .unwrap_err();
256        assert!(matches!(error, crate::NodeError::DaemonGone));
257    }
258}