[−][src]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.
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 |
| LogCx | Logging context |
Traits
| Visitable | This trait allows a |