Crate stakker_log 

Logging macros for Stakker

There are five severity-based logging macros (trace!, debug!, info!, warn! and error!) and one macro designed for logging records that have a fixed tag and no freeform text (audit!). Examples:

error!([cx], addr: %src_addr, port, "Failed to connect: {}", err);
audit!([cx], TcpConnectFailure, addr: %src_addr, port);

The severity-based macros like error! all work the same way. The [cx] comes first, followed by an optional target specification (target: "target-name"), followed by optional key-value pairs, followed by a format-string and its arguments.

For audit!, [cx] comes first, followed by a tag for the record, followed by key-value pairs. The tag will normally be a plain identifier, but it could also be a literal string or an expression in parentheses which will be formatted to generate the tag.

[cx] can refer to either an actor context (stakker::Cx) or a LogCx. Where the call is not being made from a context that provides a LogID, [core] may be passed instead of [cx], which gives a LogID of zero. It’s possible to log against a specific actor or other LogID source by using [source, core] instead of [cx], which takes the LogID from that source using a source.access_log_id() call. (In general the [a] form must support a.access_log_id() and a.access_core(), and the [a,b] form must support a.access_log_id() and b.access_core().)

For key-value pairs, the most general form is "key": expr, but there are a number of shortcuts as follows:

Shortcut	Equivalent
size: file_size	"size": file_size
size	"size": size
packet.size	"size": packet.size
tcp.packet.size	"size": tcp.packet.size
%src_addr	"src_addr": format_args!("{}", src_addr)
src_addr: %addr	"src_addr": format_args!("{}", addr)
?stream	"stream": format_args!("{:?}", stream)
stream: ?input_stream	"stream": format_args!("{:?}", input_stream)

Conversion of values is determined by implementation of the Visitable trait. All Rust primitives and standard collections are supported by Visitable. For your own types, there are two possibilities: either implement Display or Debug and use % or ?, or else implement Visitable directly. The advantage of implementing Visitable is that in addition to mapping to a primitive instead of a string, you could also output a structured value such as an array or map to represent your type.

Logging output

You can write you own code which accepts a &dyn Fn(&mut dyn LogVisitor), and calls it to receive all the logging data. There are also provided types for JSON output (KvToJson) and simple human-readable output (KvSingleLine).

Macros

audit

Log an audit record

debug

Log debugging with context info

error

Log an error with context info

info

Log information with context info

log

Internal macro which handles translation to a log call

trace

Log tracing with context info

warn

Log a warning with context info

Structs

KvSingleLine

Single-line rendering of key-value pairs

KvToJson

JSON rendering of key-value pairs

LogCx

Logging context

Traits

Visitable

This trait allows a stakker::LogVisitor to visit various fundamental Rust types and collections.