Skip to main content

Logger

Struct Logger 

Source
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 AuditEventType except Diagnostic — 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

Source

pub fn builder(backend: Arc<dyn AuditBackend>) -> LoggerBuilder

Start building a logger writing to backend.

Source

pub fn min_level(&self) -> AuditSeverity

The current minimum level for diagnostic events.

Source

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.

Source

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.

Source

pub fn filter(&self) -> Option<&LiveFilter>

The filter applied to diagnostics, if one is configured.

Source

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.

Source

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());
Source

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.

Source

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.

Source

pub fn diagnostic<S: Into<String>>(&self, level: AuditSeverity, message: S)

Write a diagnostic record at level, subject to the level filter.

Source

pub fn trace<S: Into<String>>(&self, message: S)

Write a Trace diagnostic.

Source

pub fn debug<S: Into<String>>(&self, message: S)

Write a Debug diagnostic.

Source

pub fn info<S: Into<String>>(&self, message: S)

Write an Info diagnostic.

Source

pub fn warn<S: Into<String>>(&self, message: S)

Write a Warning diagnostic.

Source

pub fn error<S: Into<String>>(&self, message: S)

Write an Error diagnostic.

Source

pub fn flush(&self)

Flush the underlying backend.

Source

pub fn identity(&self) -> &Provenance

The service identity stamped on every event this logger writes.

Source

pub fn backend(&self) -> &Arc<dyn AuditBackend> ⓘ

The backend this logger writes to.

Source

pub fn integrity(&self) -> &Arc<dyn AuditIntegrity> ⓘ

The integrity mechanism applied to admitted events.

Trait Implementations§

Source§

impl Debug for Logger

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl !Freeze for Logger

§

impl !RefUnwindSafe for Logger

§

impl !UnwindSafe for Logger

§

impl Forget for Logger

§

impl Move for Logger

§

impl Send for Logger

§

impl Sync for Logger

§

impl Unpin for Logger

§

impl UnsafeUnpin for Logger

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more