7 releases (2 stable)

Uses new Rust 2021

2.0.0 Jul 19, 2022
1.0.0 Mar 16, 2022
0.3.1 Jul 16, 2021
0.3.0 Feb 13, 2020
0.1.0 Nov 21, 2019

#100 in Debugging

Download history 134/week @ 2022-06-08 220/week @ 2022-06-15 202/week @ 2022-06-22 295/week @ 2022-06-29 241/week @ 2022-07-06 125/week @ 2022-07-13 224/week @ 2022-07-20 505/week @ 2022-07-27 408/week @ 2022-08-03 557/week @ 2022-08-10 787/week @ 2022-08-17 563/week @ 2022-08-24 798/week @ 2022-08-31 660/week @ 2022-09-07 149/week @ 2022-09-14 192/week @ 2022-09-21

1,929 downloads per month
Used in 4 crates (3 directly)

Apache-2.0

50KB
1K SLoC

witchcraft-rust-logging

CircleCI

Logging infrastructure for Witchcraft services.

witchcraft-log

Documentation

A structured logging facade. It differs from the traditional log by adding a concept of "safety" to log parameters and allowing a conjure-error Error to be attached to log records.

witchcraft-metrics

Documentation

A general-purpose metrics library. The design of the crate is based fairly closely off of the Dropwizard Metrics library from the Java ecosystem.

License

This repository is made available under the Apache 2.0 License.


lib.rs:

A structured logging facade for Witchcraft servers.

witchcraft-log is structured quite similarly to the standard Rust log crate. Its usage in libraries versus executables, log levels, etc are all mostly identical. However, witchcraft-log does differ from log in some key ways.

Structured Logging

Witchcraft logs are structured. Rather than including runtime information by interpolating them into the log message, information is included via a separate set of parameters. Parameters are partitioned into "safe" parameters and "unsafe" parameters. Safety in this context is not safety in the traditional Rust sense of memory safety, but instead safety against information leakage. Safe parameters do not contain any sensitive information about use of a service and can be exfiltrated from a specific environment, while unsafe parameters contain sensitive information that should not leave the environment at all. For example, the amount of memory used to process a request could be a safe parameter, while information about the user executing the request could be an unsafe parameter.

Parameters can be arbitrary serde-serializable values. Note, however, that loggers may commonly serialize parameters to JSON, so values that cannot be serialized into JSON are not recommended.

All dynamic information in the log record should be represented via parameters. In fact, Witchcraft-log requires the log message to be a static string - no interpolation of any kind can be performed. This means that the message itself can always be considered safe.

Examples

# let (user_id, memory_overhead) = ("", "");
// with the standard log crate
log::info!("ran a request for {} using {} bytes of memory", user_id, memory_overhead);

// with the witchcraft-log crate
witchcraft_log::info!("ran a request", safe: { memory: memory_overhead }, unsafe: { user: user_id });

Errors

Additionally, a conjure_error::Error can be associated with a log message. Since many logs occur due to an error, this allows more information about the error (e.g. its stacktrace) to be automatically included in the record.

Examples

# fn shave_a_yak(_: ()) -> Result<(), conjure_error::Error> { Ok(()) }
# let my_yak = ();
if let Err(e) = shave_a_yak(my_yak) {
    witchcraft_log::warn!("error shaving a yak", safe: { yak: my_yak }, error: e);
}

Bridging

Even when an application is using witchcraft-log, many of its dependencies may still use the log crate. The bridge module provides functionality to forward records from the log crate to witchcraft-log.

Dependencies

~7–13MB
~252K SLoC