pub struct Logger { /* private fields */ }Expand description
Writes audit events, applying a two-tier admission policy before any integrity metadata is attached.
§Admission policy
- Security events — every
AuditEventTypeexceptDiagnostic— are always written, whatever the level threshold is. An operational setting must not be able to shrink the compliance record. - Diagnostic events are written only when their severity is at least the configured minimum level.
§Examples
use ash_log::*;
use std::sync::Arc;
let logger = Logger::builder(Arc::new(StdoutAuditBackend))
.integrity(Arc::new(SequenceIntegrity::new()))
.min_level(AuditSeverity::Warning)
.build();
// Dropped: diagnostic below the threshold.
logger.log(AuditEvent::diagnostic("cache warm").severity(AuditSeverity::Debug).build());
// Written: security events ignore the threshold entirely.
logger.log(
AuditEvent::builder()
.event_type(AuditEventType::AuthenticationAttempt)
.principal("alice@example.com")
.result(AuditResult::Success)
.severity(AuditSeverity::Info)
.build(),
);Implementations§
Source§impl Logger
impl Logger
Sourcepub fn builder(backend: Arc<dyn AuditBackend>) -> LoggerBuilder
pub fn builder(backend: Arc<dyn AuditBackend>) -> LoggerBuilder
Start building a logger writing to backend.
Sourcepub fn min_level(&self) -> AuditSeverity
pub fn min_level(&self) -> AuditSeverity
The current minimum level for diagnostic events.
Sourcepub fn set_min_level(&self, level: AuditSeverity)
pub fn set_min_level(&self, level: AuditSeverity)
Change the minimum level for diagnostic events at runtime.
Security events are unaffected: they are admitted at any threshold.
Sourcepub fn admits(&self, event: &AuditEvent) -> bool
pub fn admits(&self, event: &AuditEvent) -> bool
Whether event would be written at the current threshold.
Useful to skip building an expensive event that would be dropped. The
answer can change between this call and log if another
thread adjusts the level; that only affects diagnostics.
Sourcepub fn filter(&self) -> Option<&LiveFilter>
pub fn filter(&self) -> Option<&LiveFilter>
The filter applied to diagnostics, if one is configured.
Sourcepub fn admits_diagnostic(&self, severity: AuditSeverity, module: &str) -> bool
pub fn admits_diagnostic(&self, severity: AuditSeverity, module: &str) -> bool
Whether a diagnostic at severity from module would be recorded.
The diagnostic macros call this before formatting their arguments, so a dropped record costs a threshold lookup rather than an allocation. It consults the per-module filter, which the logger’s base level alone cannot do — without it a directive could only ever tighten the base threshold, never loosen it for one module.
Security events are not routed through here: they are admitted unconditionally.
Sourcepub fn observe_hlc(
&self,
observed: HlcTimestamp,
) -> Result<HlcTimestamp, HlcError>
pub fn observe_hlc( &self, observed: HlcTimestamp, ) -> Result<HlcTimestamp, HlcError>
Advance this logger’s clock past a timestamp observed from elsewhere.
Call this when a request arrives carrying an upstream timestamp. Every event this logger records afterwards is then ordered strictly after the upstream event, without the two hosts’ wall clocks having to agree.
Returns the resulting timestamp, or the clock error. An error means the observation was rejected — most often because the peer’s timestamp is implausibly far ahead — and this logger’s ordering is unaffected.
Does nothing and returns Ok with the current time if no clock is
configured.
§Errors
Returns HlcError if the system clock is before the
Unix epoch, the observed timestamp exceeds the clock’s maximum drift, or
the logical counter would overflow.
§Examples
use ash_log::*;
use std::sync::Arc;
let clock = Arc::new(HlcClock::new());
let logger = Logger::builder(Arc::new(NoopAuditBackend))
.clock(clock.clone())
.build();
// A timestamp that arrived on an inbound request.
let upstream = HlcClock::new().now().unwrap();
logger.observe_hlc(upstream).unwrap();
// Events recorded from here on are ordered after `upstream`.
assert!(upstream < logger.hlc_now().unwrap());Sourcepub fn hlc_now(&self) -> Option<HlcTimestamp>
pub fn hlc_now(&self) -> Option<HlcTimestamp>
The current timestamp from this logger’s clock, for stamping an outgoing request so a downstream service can order its events after this one.
Returns None when no clock is configured or the clock errored.
Sourcepub fn log(&self, event: AuditEvent)
pub fn log(&self, event: AuditEvent)
Apply the admission policy, then stamp and write the event.
Filtering happens before AuditIntegrity::add_integrity, so a
dropped event never consumes a chain position and the resulting log
verifies.
Sourcepub fn diagnostic<S: Into<String>>(&self, level: AuditSeverity, message: S)
pub fn diagnostic<S: Into<String>>(&self, level: AuditSeverity, message: S)
Write a diagnostic record at level, subject to the level filter.
Sourcepub fn identity(&self) -> &Provenance
pub fn identity(&self) -> &Provenance
The service identity stamped on every event this logger writes.
Sourcepub fn backend(&self) -> &Arc<dyn AuditBackend> ⓘ
pub fn backend(&self) -> &Arc<dyn AuditBackend> ⓘ
The backend this logger writes to.
Sourcepub fn integrity(&self) -> &Arc<dyn AuditIntegrity> ⓘ
pub fn integrity(&self) -> &Arc<dyn AuditIntegrity> ⓘ
The integrity mechanism applied to admitted events.