Skip to main content

ash_log/
logger.rs

1//! A logger that owns a backend, an integrity mechanism, and an admission
2//! policy, so events are filtered before they are stamped.
3//!
4//! # Why this type exists
5//!
6//! [`AuditIntegrity::add_integrity`] advances the chain every time it is
7//! called. Dropping an event *after* stamping therefore leaves a gap, and the
8//! resulting log fails verification even though nobody tampered with it. The
9//! only safe order is to decide admission first and stamp second.
10//!
11//! [`Logger`] makes that order structural rather than a convention: filtering
12//! happens inside [`Logger::log`], before the integrity mechanism is consulted,
13//! so a caller cannot get it wrong.
14
15use super::{
16    AuditBackend, AuditEvent, AuditIntegrity, AuditSeverity, LiveFilter, NoRedaction, Provenance,
17    Redactor, Scope,
18};
19#[cfg(feature = "hlc")]
20use super::{EventClock, HlcClock, HlcTimestamp};
21use std::sync::Arc;
22use std::sync::atomic::{AtomicU8, Ordering};
23
24/// Encodes an [`AuditSeverity`] as a `u8` for atomic storage, preserving order.
25fn level_to_u8(level: AuditSeverity) -> u8 {
26    match level {
27        AuditSeverity::Trace => 0,
28        AuditSeverity::Debug => 1,
29        AuditSeverity::Info => 2,
30        AuditSeverity::Warning => 3,
31        AuditSeverity::Error => 4,
32        AuditSeverity::Critical => 5,
33    }
34}
35
36/// Inverse of [`level_to_u8`]. Out-of-range values clamp to the most
37/// restrictive level, so a corrupted store can never widen what is admitted.
38fn u8_to_level(raw: u8) -> AuditSeverity {
39    match raw {
40        0 => AuditSeverity::Trace,
41        1 => AuditSeverity::Debug,
42        2 => AuditSeverity::Info,
43        3 => AuditSeverity::Warning,
44        4 => AuditSeverity::Error,
45        _ => AuditSeverity::Critical,
46    }
47}
48
49/// Writes audit events, applying a two-tier admission policy before any
50/// integrity metadata is attached.
51///
52/// # Admission policy
53///
54/// - **Security events** — every [`AuditEventType`](crate::AuditEventType)
55///   except [`Diagnostic`](crate::AuditEventType::Diagnostic) — are always
56///   written, whatever the level threshold is. An operational setting must not
57///   be able to shrink the compliance record.
58/// - **Diagnostic events** are written only when their severity is at least the
59///   configured minimum level.
60///
61/// # Examples
62///
63/// ```rust
64/// use ash_log::*;
65/// use std::sync::Arc;
66///
67/// let logger = Logger::builder(Arc::new(StdoutAuditBackend))
68///     .integrity(Arc::new(SequenceIntegrity::new()))
69///     .min_level(AuditSeverity::Warning)
70///     .build();
71///
72/// // Dropped: diagnostic below the threshold.
73/// logger.log(AuditEvent::diagnostic("cache warm").severity(AuditSeverity::Debug).build());
74///
75/// // Written: security events ignore the threshold entirely.
76/// logger.log(
77///     AuditEvent::builder()
78///         .event_type(AuditEventType::AuthenticationAttempt)
79///         .principal("alice@example.com")
80///         .result(AuditResult::Success)
81///         .severity(AuditSeverity::Info)
82///         .build(),
83/// );
84/// ```
85pub struct Logger {
86    backend: Arc<dyn AuditBackend>,
87    integrity: Arc<dyn AuditIntegrity>,
88    min_level: AtomicU8,
89    identity: Provenance,
90    redactor: Arc<dyn Redactor>,
91    filter: Option<LiveFilter>,
92    #[cfg(feature = "hlc")]
93    clock: Option<Arc<HlcClock>>,
94}
95
96impl Logger {
97    /// Start building a logger writing to `backend`.
98    #[must_use]
99    pub fn builder(backend: Arc<dyn AuditBackend>) -> LoggerBuilder {
100        LoggerBuilder {
101            backend,
102            integrity: None,
103            min_level: AuditSeverity::Info,
104            identity: Provenance::new(),
105            redactor: None,
106            filter: None,
107            #[cfg(feature = "hlc")]
108            clock: None,
109        }
110    }
111
112    /// The current minimum level for diagnostic events.
113    #[must_use]
114    pub fn min_level(&self) -> AuditSeverity {
115        u8_to_level(self.min_level.load(Ordering::Relaxed))
116    }
117
118    /// Change the minimum level for diagnostic events at runtime.
119    ///
120    /// Security events are unaffected: they are admitted at any threshold.
121    pub fn set_min_level(&self, level: AuditSeverity) {
122        self.min_level.store(level_to_u8(level), Ordering::Relaxed);
123    }
124
125    /// Whether `event` would be written at the current threshold.
126    ///
127    /// Useful to skip building an expensive event that would be dropped. The
128    /// answer can change between this call and [`log`](Self::log) if another
129    /// thread adjusts the level; that only affects diagnostics.
130    #[must_use]
131    pub fn admits(&self, event: &AuditEvent) -> bool {
132        if event.event_type.is_security_relevant() {
133            return true;
134        }
135        event.severity >= self.threshold_for(event)
136    }
137
138    /// The threshold applying to `event`.
139    ///
140    /// A per-module directive wins where one matches; otherwise the logger's
141    /// own level decides. A filter can therefore both loosen and tighten the
142    /// base threshold for a specific module, which is the point of having one.
143    fn threshold_for(&self, event: &AuditEvent) -> AuditSeverity {
144        let Some(filter) = &self.filter else {
145            return self.min_level();
146        };
147        let Some(module) = event.provenance.module.as_deref() else {
148            return self.min_level();
149        };
150        if filter.is_empty() {
151            return self.min_level();
152        }
153        filter.level_for(module)
154    }
155
156    /// The filter applied to diagnostics, if one is configured.
157    #[must_use]
158    pub fn filter(&self) -> Option<&LiveFilter> {
159        self.filter.as_ref()
160    }
161
162    /// Whether a diagnostic at `severity` from `module` would be recorded.
163    ///
164    /// The diagnostic macros call this before formatting their arguments, so a
165    /// dropped record costs a threshold lookup rather than an allocation. It
166    /// consults the per-module filter, which the logger's base level alone
167    /// cannot do — without it a directive could only ever tighten the base
168    /// threshold, never loosen it for one module.
169    ///
170    /// Security events are not routed through here: they are admitted
171    /// unconditionally.
172    #[must_use]
173    pub fn admits_diagnostic(&self, severity: AuditSeverity, module: &str) -> bool {
174        let threshold = match &self.filter {
175            Some(filter) if !filter.is_empty() => filter.level_for(module),
176            _ => self.min_level(),
177        };
178        severity >= threshold
179    }
180
181    /// Stamp `event` with the configured clock, if there is one.
182    ///
183    /// A clock error never costs an event: the record is written without an
184    /// `hlc` field rather than dropped. Losing the causal ordering of one entry
185    /// is a far smaller failure than losing the entry.
186    #[cfg(feature = "hlc")]
187    fn stamp_hlc(&self, event: &mut AuditEvent) {
188        if event.hlc.is_some() {
189            return; // An explicit timestamp on the event wins.
190        }
191        if let Some(clock) = &self.clock
192            && let Ok(timestamp) = clock.now()
193        {
194            event.hlc = Some(EventClock::from(timestamp));
195        }
196    }
197
198    /// Advance this logger's clock past a timestamp observed from elsewhere.
199    ///
200    /// Call this when a request arrives carrying an upstream timestamp. Every
201    /// event this logger records afterwards is then ordered strictly after the
202    /// upstream event, without the two hosts' wall clocks having to agree.
203    ///
204    /// Returns the resulting timestamp, or the clock error. An error means the
205    /// observation was rejected — most often because the peer's timestamp is
206    /// implausibly far ahead — and this logger's ordering is unaffected.
207    ///
208    /// Does nothing and returns `Ok` with the current time if no clock is
209    /// configured.
210    ///
211    /// # Errors
212    ///
213    /// Returns [`HlcError`](crate::HlcError) if the system clock is before the
214    /// Unix epoch, the observed timestamp exceeds the clock's maximum drift, or
215    /// the logical counter would overflow.
216    ///
217    /// # Examples
218    ///
219    /// ```rust
220    /// use ash_log::*;
221    /// use std::sync::Arc;
222    ///
223    /// let clock = Arc::new(HlcClock::new());
224    /// let logger = Logger::builder(Arc::new(NoopAuditBackend))
225    ///     .clock(clock.clone())
226    ///     .build();
227    ///
228    /// // A timestamp that arrived on an inbound request.
229    /// let upstream = HlcClock::new().now().unwrap();
230    /// logger.observe_hlc(upstream).unwrap();
231    ///
232    /// // Events recorded from here on are ordered after `upstream`.
233    /// assert!(upstream < logger.hlc_now().unwrap());
234    /// ```
235    #[cfg(feature = "hlc")]
236    pub fn observe_hlc(&self, observed: HlcTimestamp) -> Result<HlcTimestamp, crate::HlcError> {
237        match &self.clock {
238            Some(clock) => clock.recv(observed),
239            None => Ok(observed),
240        }
241    }
242
243    /// The current timestamp from this logger's clock, for stamping an outgoing
244    /// request so a downstream service can order its events after this one.
245    ///
246    /// Returns `None` when no clock is configured or the clock errored.
247    #[cfg(feature = "hlc")]
248    #[must_use]
249    pub fn hlc_now(&self) -> Option<HlcTimestamp> {
250        self.clock.as_ref().and_then(|clock| clock.now().ok())
251    }
252
253    /// Apply the admission policy, then stamp and write the event.
254    ///
255    /// Filtering happens *before* [`AuditIntegrity::add_integrity`], so a
256    /// dropped event never consumes a chain position and the resulting log
257    /// verifies.
258    pub fn log(&self, event: AuditEvent) {
259        if !self.admits(&event) {
260            return;
261        }
262
263        let mut event = event;
264        if !self.identity.is_empty() {
265            event.provenance = std::mem::take(&mut event.provenance).or_fill_from(&self.identity);
266        }
267        // Scope fields fill in before redaction, so anything a scope supplies
268        // is scrubbed on the same terms as a call site's own metadata.
269        Scope::apply_current(&mut event);
270        #[cfg(feature = "hlc")]
271        self.stamp_hlc(&mut event);
272        // Before `add_integrity`: a secret scrubbed afterwards would leave a
273        // MAC over the unredacted value, so the log would leak *and* fail to
274        // verify.
275        self.redactor.redact_event(&mut event);
276        self.integrity.add_integrity(&mut event);
277        self.backend.log_audit(&event);
278    }
279
280    /// Write a diagnostic record at `level`, subject to the level filter.
281    #[track_caller]
282    pub fn diagnostic<S: Into<String>>(&self, level: AuditSeverity, message: S) {
283        self.log(
284            AuditEvent::diagnostic(message)
285                .severity(level)
286                .provenance(Provenance::capture())
287                .build(),
288        );
289    }
290
291    /// Write a [`Trace`](AuditSeverity::Trace) diagnostic.
292    #[track_caller]
293    pub fn trace<S: Into<String>>(&self, message: S) {
294        self.diagnostic(AuditSeverity::Trace, message);
295    }
296
297    /// Write a [`Debug`](AuditSeverity::Debug) diagnostic.
298    #[track_caller]
299    pub fn debug<S: Into<String>>(&self, message: S) {
300        self.diagnostic(AuditSeverity::Debug, message);
301    }
302
303    /// Write an [`Info`](AuditSeverity::Info) diagnostic.
304    #[track_caller]
305    pub fn info<S: Into<String>>(&self, message: S) {
306        self.diagnostic(AuditSeverity::Info, message);
307    }
308
309    /// Write a [`Warning`](AuditSeverity::Warning) diagnostic.
310    #[track_caller]
311    pub fn warn<S: Into<String>>(&self, message: S) {
312        self.diagnostic(AuditSeverity::Warning, message);
313    }
314
315    /// Write an [`Error`](AuditSeverity::Error) diagnostic.
316    #[track_caller]
317    pub fn error<S: Into<String>>(&self, message: S) {
318        self.diagnostic(AuditSeverity::Error, message);
319    }
320
321    /// Flush the underlying backend.
322    pub fn flush(&self) {
323        self.backend.flush();
324    }
325
326    /// The service identity stamped on every event this logger writes.
327    #[must_use]
328    pub fn identity(&self) -> &Provenance {
329        &self.identity
330    }
331
332    /// The backend this logger writes to.
333    #[must_use]
334    pub fn backend(&self) -> &Arc<dyn AuditBackend> {
335        &self.backend
336    }
337
338    /// The integrity mechanism applied to admitted events.
339    #[must_use]
340    pub fn integrity(&self) -> &Arc<dyn AuditIntegrity> {
341        &self.integrity
342    }
343}
344
345impl std::fmt::Debug for Logger {
346    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
347        f.debug_struct("Logger")
348            .field("min_level", &self.min_level())
349            .finish_non_exhaustive()
350    }
351}
352
353/// Builder for [`Logger`].
354pub struct LoggerBuilder {
355    backend: Arc<dyn AuditBackend>,
356    integrity: Option<Arc<dyn AuditIntegrity>>,
357    min_level: AuditSeverity,
358    identity: Provenance,
359    redactor: Option<Arc<dyn Redactor>>,
360    filter: Option<LiveFilter>,
361    #[cfg(feature = "hlc")]
362    clock: Option<Arc<HlcClock>>,
363}
364
365impl LoggerBuilder {
366    /// Set the integrity mechanism. Defaults to
367    /// [`NoIntegrity`](crate::NoIntegrity).
368    #[must_use]
369    pub fn integrity(mut self, integrity: Arc<dyn AuditIntegrity>) -> Self {
370        self.integrity = Some(integrity);
371        self
372    }
373
374    /// Set the minimum level for diagnostic events. Defaults to
375    /// [`Info`](AuditSeverity::Info).
376    #[must_use]
377    pub fn min_level(mut self, level: AuditSeverity) -> Self {
378        self.min_level = level;
379        self
380    }
381
382    /// Set the service identity stamped on every event.
383    ///
384    /// Fields left unset on an individual event are filled from this, so a
385    /// service name, version, and host are recorded once rather than at every
386    /// call site. Identity is part of the signed event, not `metadata`.
387    #[must_use]
388    pub fn identity(mut self, identity: Provenance) -> Self {
389        self.identity = identity;
390        self
391    }
392
393    /// Give the logger a Hybrid Logical Clock.
394    ///
395    /// Every event it writes is then stamped with a monotonic causal
396    /// timestamp, inside the signed canonical form. Share one `Arc<HlcClock>`
397    /// across the loggers of a single service so their events stay mutually
398    /// ordered.
399    #[cfg(feature = "hlc")]
400    #[must_use]
401    pub fn clock(mut self, clock: Arc<HlcClock>) -> Self {
402        self.clock = Some(clock);
403        self
404    }
405
406    /// Set the redactor applied to every event before it is stamped.
407    ///
408    /// Defaults to [`NoRedaction`], so redaction is opt-in.
409    #[must_use]
410    pub fn redact(mut self, redactor: Arc<dyn Redactor>) -> Self {
411        self.redactor = Some(redactor);
412        self
413    }
414
415    /// Apply per-module level directives on top of the base threshold.
416    ///
417    /// The handle can be updated at runtime, retuning this logger without
418    /// rebuilding it. Only diagnostics are affected; security events are
419    /// admitted whatever any filter says.
420    #[must_use]
421    pub fn filter(mut self, filter: LiveFilter) -> Self {
422        self.filter = Some(filter);
423        self
424    }
425
426    /// Build the logger.
427    #[must_use]
428    pub fn build(self) -> Logger {
429        Logger {
430            backend: self.backend,
431            integrity: self
432                .integrity
433                .unwrap_or_else(|| Arc::new(crate::NoIntegrity)),
434            min_level: AtomicU8::new(level_to_u8(self.min_level)),
435            identity: self.identity,
436            redactor: self.redactor.unwrap_or_else(|| Arc::new(NoRedaction)),
437            filter: self.filter,
438            #[cfg(feature = "hlc")]
439            clock: self.clock,
440        }
441    }
442}
443
444#[cfg(test)]
445mod tests {
446    use super::*;
447    use crate::{AuditEventType, AuditResult, NoopAuditBackend, SequenceIntegrity};
448    use std::sync::Mutex;
449
450    /// Captures written events so tests can assert on what survived filtering.
451    #[derive(Default)]
452    struct CapturingBackend(Mutex<Vec<AuditEvent>>);
453
454    impl CapturingBackend {
455        fn events(&self) -> Vec<AuditEvent> {
456            self.0
457                .lock()
458                .unwrap_or_else(std::sync::PoisonError::into_inner)
459                .clone()
460        }
461    }
462
463    impl AuditBackend for CapturingBackend {
464        fn log_audit(&self, event: &AuditEvent) {
465            self.0
466                .lock()
467                .unwrap_or_else(std::sync::PoisonError::into_inner)
468                .push(event.clone());
469        }
470    }
471
472    fn security_event(severity: AuditSeverity) -> AuditEvent {
473        AuditEvent::builder()
474            .event_type(AuditEventType::AuthenticationAttempt)
475            .result(AuditResult::Success)
476            .severity(severity)
477            .build()
478    }
479
480    fn logger_at(level: AuditSeverity) -> (Logger, Arc<CapturingBackend>) {
481        let backend = Arc::new(CapturingBackend::default());
482        let logger = Logger::builder(backend.clone())
483            .integrity(Arc::new(SequenceIntegrity::new()))
484            .min_level(level)
485            .build();
486        (logger, backend)
487    }
488
489    #[test]
490    fn test_diagnostics_below_the_threshold_are_dropped() {
491        let (logger, backend) = logger_at(AuditSeverity::Warning);
492
493        logger.trace("trace");
494        logger.debug("debug");
495        logger.info("info");
496        logger.warn("warning");
497        logger.error("error");
498
499        let written: Vec<AuditSeverity> = backend.events().iter().map(|e| e.severity).collect();
500        assert_eq!(
501            written,
502            vec![AuditSeverity::Warning, AuditSeverity::Error],
503            "only diagnostics at or above the threshold are written"
504        );
505    }
506
507    #[test]
508    fn test_security_events_ignore_the_threshold() {
509        // The whole point of the two-tier policy: an operational setting must
510        // not be able to shrink the compliance record.
511        let (logger, backend) = logger_at(AuditSeverity::Critical);
512
513        logger.log(security_event(AuditSeverity::Trace));
514        logger.log(security_event(AuditSeverity::Info));
515        logger.diagnostic(AuditSeverity::Info, "should be dropped");
516
517        let events = backend.events();
518        assert_eq!(events.len(), 2, "both security events survive");
519        assert!(
520            events.iter().all(|e| e.event_type.is_security_relevant()),
521            "only the diagnostic was filtered"
522        );
523    }
524
525    #[test]
526    fn test_admits_matches_what_log_writes() {
527        let (logger, backend) = logger_at(AuditSeverity::Warning);
528
529        let low = AuditEvent::diagnostic("low")
530            .severity(AuditSeverity::Debug)
531            .build();
532        let high = AuditEvent::diagnostic("high")
533            .severity(AuditSeverity::Error)
534            .build();
535
536        assert!(!logger.admits(&low));
537        assert!(logger.admits(&high));
538
539        logger.log(low);
540        logger.log(high);
541        assert_eq!(backend.events().len(), 1, "admits agreed with log");
542    }
543
544    #[test]
545    fn test_min_level_is_adjustable_at_runtime() {
546        let (logger, backend) = logger_at(AuditSeverity::Error);
547        assert_eq!(logger.min_level(), AuditSeverity::Error);
548
549        logger.info("dropped");
550        logger.set_min_level(AuditSeverity::Debug);
551        logger.info("kept");
552
553        assert_eq!(logger.min_level(), AuditSeverity::Debug);
554        let events = backend.events();
555        assert_eq!(events.len(), 1);
556        assert_eq!(events[0].message.as_deref(), Some("kept"));
557    }
558
559    #[test]
560    fn test_level_round_trips_through_atomic_storage() {
561        for level in [
562            AuditSeverity::Trace,
563            AuditSeverity::Debug,
564            AuditSeverity::Info,
565            AuditSeverity::Warning,
566            AuditSeverity::Error,
567            AuditSeverity::Critical,
568        ] {
569            assert_eq!(u8_to_level(level_to_u8(level)), level);
570        }
571        // An out-of-range value must clamp to the most restrictive level rather
572        // than widening what is admitted.
573        assert_eq!(u8_to_level(200), AuditSeverity::Critical);
574    }
575
576    #[test]
577    fn test_default_builder_uses_noop_integrity_and_info() {
578        let logger = Logger::builder(Arc::new(NoopAuditBackend)).build();
579        assert_eq!(logger.min_level(), AuditSeverity::Info);
580        logger.debug("dropped by default threshold");
581    }
582
583    #[test]
584    fn test_filtered_events_do_not_consume_a_sequence_number() {
585        // Regression guard for the ordering hazard: a dropped event must never
586        // advance the integrity mechanism.
587        let (logger, backend) = logger_at(AuditSeverity::Error);
588
589        logger.debug("dropped");
590        logger.debug("dropped");
591        logger.error("kept");
592
593        let events = backend.events();
594        assert_eq!(events.len(), 1);
595        assert_eq!(
596            events[0]
597                .metadata
598                .get("sequence")
599                .and_then(serde_json::Value::as_u64),
600            Some(0),
601            "the first written event must hold sequence 0, not 2"
602        );
603    }
604
605    #[cfg(feature = "hlc")]
606    mod hlc {
607        use super::*;
608        use crate::{EventClock, HlcClock};
609
610        #[test]
611        fn test_events_are_stamped_when_a_clock_is_configured() {
612            let backend = Arc::new(CapturingBackend::default());
613            let logger = Logger::builder(backend.clone())
614                .clock(Arc::new(HlcClock::new()))
615                .build();
616
617            logger.info("first");
618            logger.info("second");
619
620            let events = backend.events();
621            let first = events[0].hlc.expect("stamped");
622            let second = events[1].hlc.expect("stamped");
623            assert!(
624                first.happened_before(second),
625                "later events carry strictly later timestamps"
626            );
627        }
628
629        #[test]
630        fn test_no_clock_leaves_the_field_absent() {
631            let backend = Arc::new(CapturingBackend::default());
632            let logger = Logger::builder(backend.clone()).build();
633
634            logger.info("unstamped");
635
636            assert_eq!(
637                backend.events()[0].hlc,
638                None,
639                "the field costs nothing until a clock is configured"
640            );
641        }
642
643        #[test]
644        fn test_stamps_are_monotonic_across_threads() {
645            // One clock shared by several loggers must still produce a total
646            // order, or concurrent events could not be sequenced.
647            let backend = Arc::new(CapturingBackend::default());
648            let clock = Arc::new(HlcClock::new());
649            let logger = Arc::new(
650                Logger::builder(backend.clone())
651                    .clock(clock.clone())
652                    .build(),
653            );
654
655            let mut handles = Vec::new();
656            for n in 0..8 {
657                let logger = logger.clone();
658                handles.push(std::thread::spawn(move || {
659                    for i in 0..16 {
660                        logger.info(format!("thread {n} event {i}"));
661                    }
662                }));
663            }
664            for handle in handles {
665                handle.join().expect("worker thread panicked");
666            }
667
668            let mut stamps: Vec<EventClock> = backend
669                .events()
670                .iter()
671                .map(|e| e.hlc.expect("stamped"))
672                .collect();
673            assert_eq!(stamps.len(), 128);
674
675            let before = stamps.len();
676            stamps.sort_unstable();
677            stamps.dedup();
678            assert_eq!(
679                stamps.len(),
680                before,
681                "every event gets a distinct timestamp, so the order is total"
682            );
683        }
684
685        #[test]
686        fn test_an_explicit_timestamp_on_the_event_wins() {
687            let backend = Arc::new(CapturingBackend::default());
688            let logger = Logger::builder(backend.clone())
689                .clock(Arc::new(HlcClock::new()))
690                .build();
691
692            let pinned = EventClock {
693                physical: 1,
694                logical: 2,
695            };
696            logger.log(
697                AuditEvent::diagnostic("preset")
698                    .severity(AuditSeverity::Info)
699                    .hlc(pinned)
700                    .build(),
701            );
702
703            assert_eq!(
704                backend.events()[0].hlc,
705                Some(pinned),
706                "a caller-supplied timestamp is not overwritten"
707            );
708        }
709
710        #[test]
711        fn test_observe_advances_the_clock_past_an_upstream_timestamp() {
712            // The cross-service case: events recorded after observing an
713            // upstream timestamp must be ordered after it, whatever the local
714            // wall clock says.
715            let backend = Arc::new(CapturingBackend::default());
716            let logger = Logger::builder(backend.clone())
717                .clock(Arc::new(HlcClock::new()))
718                .build();
719
720            let upstream = HlcClock::new().now().expect("system clock is sane");
721            logger.observe_hlc(upstream).expect("observation accepted");
722            logger.info("after the upstream event");
723
724            let stamped = backend.events()[0].hlc.expect("stamped");
725            assert!(
726                EventClock::from(upstream).happened_before(stamped),
727                "local events are ordered after the observed timestamp"
728            );
729        }
730
731        #[test]
732        fn test_observe_without_a_clock_is_inert() {
733            let logger = Logger::builder(Arc::new(NoopAuditBackend)).build();
734            let upstream = HlcClock::new().now().unwrap();
735
736            assert_eq!(
737                logger.observe_hlc(upstream),
738                Ok(upstream),
739                "a logger with no clock has no ordering to advance"
740            );
741            assert_eq!(logger.hlc_now(), None);
742        }
743
744        #[test]
745        fn test_filtered_events_do_not_consume_a_timestamp() {
746            // Stamping happens after the admission check, so a dropped
747            // diagnostic must not advance the clock.
748            let backend = Arc::new(CapturingBackend::default());
749            let clock = Arc::new(HlcClock::new());
750            let logger = Logger::builder(backend.clone())
751                .clock(clock.clone())
752                .min_level(AuditSeverity::Error)
753                .build();
754
755            logger.info("dropped");
756            let before = clock.last();
757            logger.info("also dropped");
758            assert_eq!(
759                clock.last(),
760                before,
761                "filtered events never reach the clock"
762            );
763
764            logger.error("written");
765            assert!(backend.events()[0].hlc.is_some());
766        }
767    }
768}