Trait stakker::LogVisitor

pub trait LogVisitor {
    // Required methods
    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 normally Some(key). However where this value is a member of an array the key must be None.

• All signed integer types from i8 up to i64 are passed to kv_i64, and all unsigned integer types from u8 up to u64 are passed to kv_u64.

• kv_null may be used to represent a key with presence but no value, i.e. a JSON null or Rust unit () value. It might be converted into an empty-string or true value depending on the logger if presence values are not supported downstream.

• Anything that needs to be formatted as a string, e.g. Display or Debug types, is passed through to kv_fmt using format_args!. This way the logger can format it directly into the output, avoiding the allocations that would occur if you used format!.

• Maps are introduced with a call to kv_map, then zero or more kv_* calls for the contents of that map, then a call to kv_mapend to close the map and continue at the original level.

• Arrays are introduced with a call to kv_arr, then zero or more kv_* calls for the contents of the array, then a call to kv_arrend to close the array and continue at the original level. The key argument on the kv_* calls within an array should be None.

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.

Required Methods

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>)

Implementors