#[macro_export]
macro_rules! ash_logger {
($($key:ident : $value:expr),* $(,)?) => {{
#[allow(unused_mut)]
let mut identity = $crate::Provenance::new();
#[allow(unused_mut)]
let mut builder = $crate::Logger::builder(
$crate::__ash_logger_backend!($($key : $value),*)
);
$(
$crate::__ash_logger_field!(builder, identity, $key, $value);
)*
builder.identity(identity).build()
}};
}
#[doc(hidden)]
#[macro_export]
macro_rules! __ash_logger_backend {
($($key:ident : $value:expr),* $(,)?) => {
$crate::__ash_logger_buffer!(
($crate::__ash_logger_inner_backend!($($key : $value),*))
$($key : $value),*
)
};
}
#[doc(hidden)]
#[macro_export]
macro_rules! __ash_logger_inner_backend {
(backend : $value:expr $(, $($rest:tt)*)?) => { $value };
($key:ident : $value:expr, $($rest:tt)*) => {
$crate::__ash_logger_inner_backend!($($rest)*)
};
($key:ident : $value:expr) => {
::std::sync::Arc::new($crate::StdoutAuditBackend)
};
() => { ::std::sync::Arc::new($crate::StdoutAuditBackend) };
}
#[doc(hidden)]
#[macro_export]
macro_rules! __ash_logger_buffer {
(($backend:expr) buffered : $capacity:expr $(, $($rest:tt)*)?) => {
::std::sync::Arc::new($crate::BufferedAuditBackend::new($backend, $capacity))
};
(($backend:expr) $key:ident : $value:expr, $($rest:tt)*) => {
$crate::__ash_logger_buffer!(($backend) $($rest)*)
};
(($backend:expr) $key:ident : $value:expr) => { $backend };
(($backend:expr)) => { $backend };
}
#[doc(hidden)]
#[macro_export]
macro_rules! __ash_logger_field {
($builder:ident, $identity:ident, backend, $value:expr) => {};
($builder:ident, $identity:ident, buffered, $value:expr) => {};
($builder:ident, $identity:ident, integrity, $value:expr) => {
$builder = $builder.integrity($value);
};
($builder:ident, $identity:ident, min_level, $value:expr) => {
$builder = $builder.min_level($value);
};
($builder:ident, $identity:ident, redact, $value:expr) => {
$builder = $builder.redact($value);
};
($builder:ident, $identity:ident, filter, $value:expr) => {
$builder = $builder.filter($value);
};
($builder:ident, $identity:ident, clock, $value:expr) => {
$builder = $builder.clock($value);
};
($builder:ident, $identity:ident, service, $value:expr) => {
$identity = $identity.with_service($value);
};
($builder:ident, $identity:ident, version, $value:expr) => {
$identity = $identity.with_version($value);
};
($builder:ident, $identity:ident, host, $value:expr) => {
$identity = $identity.with_host($value);
};
($builder:ident, $identity:ident, identity, $value:expr) => {
assert!(
$identity.is_empty(),
"ash_logger!: `identity:` cannot be combined with `service:`, \
`version:`, or `host:` — set those fields on the Provenance instead",
);
$identity = $value;
};
($builder:ident, $identity:ident, $key:ident, $value:expr) => {
compile_error!(concat!(
"ash_logger!: unknown key `",
stringify!($key),
"`; expected one of \
backend, buffered, integrity, min_level, redact, filter, clock, service, \
version, host, identity",
));
};
}
#[macro_export]
macro_rules! ash_diagnostic {
($logger:expr, $severity:expr, $($rest:tt)*) => {{
let logger = &$logger;
let severity = $severity;
if logger.admits_diagnostic(severity, module_path!()) {
logger.log($crate::__ash_diagnostic_event!(severity, $($rest)*));
}
}};
}
#[doc(hidden)]
#[macro_export]
macro_rules! __ash_diagnostic_event {
($severity:expr, $($rest:tt)*) => {
$crate::__ash_split_metadata!(($severity) () ; $($rest)*)
};
}
#[doc(hidden)]
#[macro_export]
macro_rules! __ash_split_metadata {
(($severity:expr) ($($fmt:tt)*) ; ; $($key:ident = $value:expr),* $(,)?) => {
$crate::AuditEvent::diagnostic(format!($($fmt)*))
.severity($severity)
.provenance($crate::__ash_provenance!())
$(.metadata(stringify!($key), $value))*
.build()
};
(($severity:expr) ($($fmt:tt)*) ;) => {
$crate::AuditEvent::diagnostic(format!($($fmt)*))
.severity($severity)
.provenance($crate::__ash_provenance!())
.build()
};
(($severity:expr) ($($fmt:tt)*) ; $head:tt $($tail:tt)*) => {
$crate::__ash_split_metadata!(($severity) ($($fmt)* $head) ; $($tail)*)
};
}
#[doc(hidden)]
#[macro_export]
macro_rules! __ash_provenance {
() => {
$crate::Provenance::capture()
.with_file(file!())
.with_line(line!())
.with_module(module_path!())
};
}
#[macro_export]
macro_rules! ash_trace {
($logger:expr, $($rest:tt)*) => {
$crate::ash_diagnostic!($logger, $crate::AuditSeverity::Trace, $($rest)*)
};
}
#[macro_export]
macro_rules! ash_debug {
($logger:expr, $($rest:tt)*) => {
$crate::ash_diagnostic!($logger, $crate::AuditSeverity::Debug, $($rest)*)
};
}
#[macro_export]
macro_rules! ash_info {
($logger:expr, $($rest:tt)*) => {
$crate::ash_diagnostic!($logger, $crate::AuditSeverity::Info, $($rest)*)
};
}
#[macro_export]
macro_rules! ash_warn {
($logger:expr, $($rest:tt)*) => {
$crate::ash_diagnostic!($logger, $crate::AuditSeverity::Warning, $($rest)*)
};
}
#[macro_export]
macro_rules! ash_error {
($logger:expr, $($rest:tt)*) => {
$crate::ash_diagnostic!($logger, $crate::AuditSeverity::Error, $($rest)*)
};
}
#[macro_export]
macro_rules! ash_audit {
($logger:expr, $event_type:ident, $result:ident $(, $($rest:tt)*)?) => {
$crate::__ash_audit_impl!(
$logger, $event_type, ($crate::__ash_audit_result!($result)) $(, $($rest)*)?
)
};
($logger:expr, $event_type:ident, $result:expr $(, $($rest:tt)*)?) => {
$crate::__ash_audit_impl!($logger, $event_type, ($result) $(, $($rest)*)?)
};
}
#[doc(hidden)]
#[macro_export]
macro_rules! __ash_audit_impl {
($logger:expr, $event_type:ident, ($result:expr) $(, $($rest:tt)*)?) => {{
let logger = &$logger;
logger.log(
$crate::__ash_audit_split!(
($event_type, $result) () ; $($($rest)*)?
)
);
}};
}
#[doc(hidden)]
#[macro_export]
macro_rules! __ash_audit_split {
(
($event_type:ident, $result:expr) ($($field:ident = $fval:expr),* $(,)?) ;
; $($key:ident = $value:expr),* $(,)?
) => {
$crate::AuditEvent::builder()
.event_type($crate::AuditEventType::$event_type)
.result($result)
.provenance($crate::__ash_provenance!())
$(.$field($fval))*
$(.metadata(stringify!($key), $value))*
.build()
};
(
($event_type:ident, $result:expr) ($($field:ident = $fval:expr),* $(,)?) ;
) => {
$crate::AuditEvent::builder()
.event_type($crate::AuditEventType::$event_type)
.result($result)
.provenance($crate::__ash_provenance!())
$(.$field($fval))*
.build()
};
(
($event_type:ident, $result:expr) ($($field:ident = $fval:expr),* $(,)?) ;
$key:ident = $value:expr ; $($tail:tt)*
) => {
$crate::__ash_audit_split!(
($event_type, $result) ($($field = $fval,)* $key = $value) ; ; $($tail)*
)
};
(
($event_type:ident, $result:expr) ($($field:ident = $fval:expr),* $(,)?) ;
$key:ident = $value:expr, $($tail:tt)*
) => {
$crate::__ash_audit_split!(
($event_type, $result) ($($field = $fval,)* $key = $value) ; $($tail)*
)
};
(
($event_type:ident, $result:expr) ($($field:ident = $fval:expr),* $(,)?) ;
$key:ident = $value:expr
) => {
$crate::__ash_audit_split!(
($event_type, $result) ($($field = $fval,)* $key = $value) ;
)
};
}
#[doc(hidden)]
#[macro_export]
macro_rules! __ash_audit_result {
(Success) => {
$crate::AuditResult::Success
};
(Failure) => {
$crate::AuditResult::Failure
};
(Denied) => {
$crate::AuditResult::Denied
};
(Violation) => {
$crate::AuditResult::Violation
};
(NotApplicable) => {
$crate::AuditResult::NotApplicable
};
($other:expr) => {
$other
};
}
#[cfg(test)]
mod tests {
use crate::{
AuditBackend, AuditEvent, AuditEventType, AuditResult, AuditSeverity, NoopAuditBackend,
SequenceIntegrity,
};
use serde_json::json;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::{Arc, Mutex, PoisonError};
#[derive(Default)]
struct Collector(Mutex<Vec<AuditEvent>>);
impl Collector {
fn events(&self) -> Vec<AuditEvent> {
self.0
.lock()
.unwrap_or_else(PoisonError::into_inner)
.clone()
}
}
impl AuditBackend for Collector {
fn log_audit(&self, event: &AuditEvent) {
self.0
.lock()
.unwrap_or_else(PoisonError::into_inner)
.push(event.clone());
}
}
#[test]
fn test_logger_macro_defaults_match_the_builder() {
let logger = ash_logger!(backend: Arc::new(NoopAuditBackend));
assert_eq!(logger.min_level(), AuditSeverity::Info);
assert!(
logger.identity().is_empty(),
"no identity keys given, so none is stamped"
);
}
#[test]
fn test_logger_macro_accepts_keys_in_any_order() {
let logger = ash_logger!(
min_level: AuditSeverity::Error,
service: "payments-api",
backend: Arc::new(NoopAuditBackend),
version: "1.2.3",
integrity: Arc::new(SequenceIntegrity::new()),
host: "pod-7",
);
assert_eq!(logger.min_level(), AuditSeverity::Error);
assert_eq!(logger.identity().service.as_deref(), Some("payments-api"));
assert_eq!(logger.identity().version.as_deref(), Some("1.2.3"));
assert_eq!(logger.identity().host.as_deref(), Some("pod-7"));
}
#[test]
fn test_diagnostic_macros_map_to_their_severities() {
let backend = Arc::new(Collector::default());
let logger = ash_logger!(
backend: backend.clone(),
min_level: AuditSeverity::Trace,
);
ash_trace!(logger, "trace");
ash_debug!(logger, "debug");
ash_info!(logger, "info");
ash_warn!(logger, "warn");
ash_error!(logger, "error");
let severities: Vec<AuditSeverity> = backend.events().iter().map(|e| e.severity).collect();
assert_eq!(
severities,
vec![
AuditSeverity::Trace,
AuditSeverity::Debug,
AuditSeverity::Info,
AuditSeverity::Warning,
AuditSeverity::Error,
]
);
}
#[test]
fn test_format_arguments_are_not_evaluated_when_filtered() {
let calls = Arc::new(AtomicUsize::new(0));
let backend = Arc::new(Collector::default());
let logger = ash_logger!(
backend: backend.clone(),
min_level: AuditSeverity::Error,
);
let counted = || {
calls.fetch_add(1, Ordering::Relaxed);
"expensive"
};
ash_debug!(logger, "{}", counted());
ash_info!(logger, "{}", counted());
assert_eq!(
calls.load(Ordering::Relaxed),
0,
"arguments below the threshold are never evaluated"
);
ash_error!(logger, "{}", counted());
assert_eq!(calls.load(Ordering::Relaxed), 1, "admitted records format");
assert_eq!(backend.events().len(), 1);
}
#[test]
fn test_format_arguments_and_metadata() {
let backend = Arc::new(Collector::default());
let logger = ash_logger!(backend: backend.clone());
let port = 8443;
ash_info!(logger, "listening on port {port}");
ash_warn!(logger, "retry {} of {}", 2, 5);
ash_error!(logger, "upload failed"; retries = 3, bucket = "audit-eu");
let events = backend.events();
assert_eq!(
events[0].message.as_deref(),
Some("listening on port 8443"),
"inline format captures work"
);
assert_eq!(events[1].message.as_deref(), Some("retry 2 of 5"));
assert_eq!(events[2].metadata["retries"], 3);
assert_eq!(events[2].metadata["bucket"], "audit-eu");
}
#[test]
fn test_call_site_provenance_is_captured() {
let backend = Arc::new(Collector::default());
let logger = ash_logger!(backend: backend.clone());
let line = line!() + 1;
ash_info!(logger, "located");
let event = &backend.events()[0];
assert_eq!(event.provenance.line, Some(line), "line is the call site");
assert_eq!(event.provenance.file.as_deref(), Some(file!()));
assert_eq!(
event.provenance.module.as_deref(),
Some(module_path!()),
"module_path! is available to a macro but not to #[track_caller]"
);
assert!(event.provenance.pid.is_some(), "capture() fills the pid");
}
#[test]
fn test_logger_identity_fills_macro_events() {
let backend = Arc::new(Collector::default());
let logger = ash_logger!(
backend: backend.clone(),
service: "gateway",
version: "0.2.0",
);
ash_info!(logger, "started");
let event = &backend.events()[0];
assert_eq!(event.provenance.service.as_deref(), Some("gateway"));
assert_eq!(event.provenance.version.as_deref(), Some("0.2.0"));
assert!(
event.provenance.file.is_some(),
"call-site fields survive the identity merge"
);
}
#[test]
fn test_buffered_key_defers_writes_until_capacity() {
let backend = Arc::new(Collector::default());
let logger = ash_logger!(
backend: backend.clone(),
buffered: 3,
min_level: AuditSeverity::Trace,
);
ash_info!(logger, "one");
ash_info!(logger, "two");
assert!(
backend.events().is_empty(),
"writes are held until the buffer fills"
);
ash_info!(logger, "three");
assert_eq!(
backend.events().len(),
3,
"the third write reaches capacity and drains the buffer"
);
}
#[test]
fn test_buffered_key_drains_on_flush() {
let backend = Arc::new(Collector::default());
let logger = ash_logger!(backend: backend.clone(), buffered: 1024);
ash_warn!(logger, "queued");
assert!(backend.events().is_empty());
logger.flush();
assert_eq!(backend.events().len(), 1, "flush drains a partial buffer");
}
#[test]
fn test_buffered_key_drains_on_drop() {
let backend = Arc::new(Collector::default());
{
let logger = ash_logger!(backend: backend.clone(), buffered: 1024);
ash_warn!(logger, "queued");
assert!(backend.events().is_empty());
}
assert_eq!(
backend.events().len(),
1,
"the buffer drains when the logger goes out of scope"
);
}
#[test]
fn test_buffered_key_composes_with_the_other_keys() {
let backend = Arc::new(Collector::default());
let logger = ash_logger!(
buffered: 2,
service: "queued-service",
backend: backend.clone(),
integrity: Arc::new(SequenceIntegrity::new()),
min_level: AuditSeverity::Warning,
);
assert_eq!(logger.min_level(), AuditSeverity::Warning);
ash_info!(logger, "filtered, never buffered");
ash_warn!(logger, "first");
ash_error!(logger, "second");
let events = backend.events();
assert_eq!(events.len(), 2);
assert_eq!(
events[0].provenance.service.as_deref(),
Some("queued-service"),
"identity still reaches events written through the buffer"
);
}
#[test]
fn test_buffering_preserves_integrity_order() {
let backend = Arc::new(Collector::default());
let logger = ash_logger!(
backend: backend.clone(),
buffered: 4,
integrity: Arc::new(SequenceIntegrity::new()),
min_level: AuditSeverity::Trace,
);
for n in 0..8 {
ash_info!(logger, "event {n}");
}
logger.flush();
let sequences: Vec<serde_json::Value> = backend
.events()
.iter()
.map(|e| e.metadata["sequence"].clone())
.collect();
let expected: Vec<serde_json::Value> = (0..8).map(|n| json!(n)).collect();
assert_eq!(
sequences, expected,
"FIFO drain keeps sequence numbers in order"
);
}
#[test]
fn test_buffered_key_without_a_backend_buffers_the_default() {
let logger = ash_logger!(buffered: 512, min_level: AuditSeverity::Critical);
ash_info!(logger, "dropped by the threshold, never buffered");
logger.flush();
}
#[test]
fn test_audit_macro_builds_security_events() {
let backend = Arc::new(Collector::default());
let logger = ash_logger!(backend: backend.clone());
ash_audit!(
logger,
AuthenticationAttempt,
Success,
principal = "alice@example.com"
);
ash_audit!(
logger,
SecurityViolation,
Denied,
principal = "bob@example.com",
method = "transfer",
error = "rate limit exceeded";
attempts = 5,
limit = 3,
);
let events = backend.events();
assert_eq!(events[0].event_type, AuditEventType::AuthenticationAttempt);
assert_eq!(events[0].result, AuditResult::Success);
assert_eq!(events[0].principal.as_deref(), Some("alice@example.com"));
assert_eq!(events[1].event_type, AuditEventType::SecurityViolation);
assert_eq!(events[1].result, AuditResult::Denied);
assert_eq!(events[1].method.as_deref(), Some("transfer"));
assert_eq!(events[1].error.as_deref(), Some("rate limit exceeded"));
assert_eq!(events[1].metadata["attempts"], 5);
assert_eq!(events[1].metadata["limit"], 3);
}
#[test]
fn test_audit_macro_ignores_the_level_threshold() {
let backend = Arc::new(Collector::default());
let logger = ash_logger!(
backend: backend.clone(),
min_level: AuditSeverity::Critical,
);
ash_error!(logger, "dropped: diagnostics are filtered");
ash_audit!(
logger,
AdminAction,
Success,
severity = AuditSeverity::Trace
);
let events = backend.events();
assert_eq!(events.len(), 1, "only the security event survives");
assert_eq!(events[0].event_type, AuditEventType::AdminAction);
assert_eq!(events[0].severity, AuditSeverity::Trace);
}
#[test]
fn test_audit_macro_accepts_a_qualified_result() {
let backend = Arc::new(Collector::default());
let logger = ash_logger!(backend: backend.clone());
ash_audit!(logger, ConnectionClosed, AuditResult::NotApplicable);
assert_eq!(backend.events()[0].result, AuditResult::NotApplicable);
}
#[test]
fn test_macros_accept_an_expression_logger() {
let backend = Arc::new(Collector::default());
let logger = Arc::new(ash_logger!(backend: backend.clone()));
ash_info!(*logger, "through a deref");
ash_audit!(*logger, AdminAction, Success);
assert_eq!(backend.events().len(), 2);
}
#[test]
fn test_events_from_macros_verify_against_the_chain() {
let backend = Arc::new(Collector::default());
let logger = ash_logger!(
backend: backend.clone(),
integrity: Arc::new(SequenceIntegrity::new()),
min_level: AuditSeverity::Warning,
);
ash_debug!(logger, "dropped");
ash_warn!(logger, "kept");
ash_audit!(logger, AuthenticationAttempt, Failure);
ash_trace!(logger, "dropped");
ash_error!(logger, "kept");
let events = backend.events();
assert_eq!(events.len(), 3);
let sequences: Vec<&serde_json::Value> =
events.iter().map(|e| &e.metadata["sequence"]).collect();
assert_eq!(
sequences,
vec![&json!(0), &json!(1), &json!(2)],
"no gaps from filtered records"
);
}
}