Trait stakker::LogVisitor [−][src]
pub trait LogVisitor { fn kv_u64(&mut self, key: Option<&str>, val: u64); fn kv_i64(&mut self, key: Option<&str>, val: i64); fn kv_f64(&mut self, key: Option<&str>, val: f64); fn kv_bool(&mut self, key: Option<&str>, val: bool); fn kv_null(&mut self, key: Option<&str>); fn kv_str(&mut self, key: Option<&str>, val: &str); fn kv_fmt(&mut self, key: Option<&str>, val: &Arguments<'_>); fn kv_map(&mut self, key: Option<&str>); fn kv_mapend(&mut self, key: Option<&str>); fn kv_arr(&mut self, key: Option<&str>); fn kv_arrend(&mut self, key: Option<&str>); }
Trait used when visiting all the log-record’s key-value pairs
This is designed as a superset of both JSON and the OpenTelemetry
KeyValueList
. Anything that cannot be represented with these
types must be logged as a string, a map or an array.
Notes:
-
The
key
argument is normallySome(key)
. However where this value is a member of an array the key must beNone
. -
All signed integer types from
i8
up toi64
are passed tokv_i64
, and all unsigned integer types fromu8
up tou64
are passed tokv_u64
. -
kv_null
may be used to represent a key with presence but no value, i.e. a JSONnull
or Rust unit()
value. It might be converted into an empty-string ortrue
value depending on the logger if presence values are not supported downstream. -
Anything that needs to be formatted as a string, e.g.
Display
orDebug
types, is passed through tokv_fmt
usingformat_args!
. This way the logger can format it directly into the output, avoiding the allocations that would occur if you usedformat!
. -
Maps are introduced with a call to
kv_map
, then zero or morekv_*
calls for the contents of that map, then a call tokv_mapend
to close the map and continue at the original level. -
Arrays are introduced with a call to
kv_arr
, then zero or morekv_*
calls for the contents of the array, then a call tokv_arrend
to close the array and continue at the original level. Thekey
argument on thekv_*
calls within an array should beNone
.
For maps and arrays, unlimited levels of nesting may be
represented. The same key must be passed to both kv_map
and
kv_mapend
(or kv_arr
and kv_arrend
), for the convenience of
different kinds of logging output methods.
A logger might not support all these data types due to limitations of the downstream format, so some data might get converted into another form if it cannot be passed on as is.
No early termination
The visitor interface doesn’t support terminating early with an
error. This is intentional. Other approaches were considered,
coded up and discarded: both std::fmt
’s approach which
effectively returns Result<(), ()>
and insists that the visitor
store the full error, and the approach used by slog
which tries
to wrap various different types within its error type. Given that
the non-error case will be most common, there is little advantage
in letting the visit terminate early. So, as for std::fmt
, if
the visitor encounters an error, it needs to store it itself. It
will then generally choose to set things up so that any further
calls are ignored. If that makes the code awkward, it can usually
be made manageable with a macro.