Crate witchcraft_log

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

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

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.

Modules

bridge

Support for forwarding messages from the log crate to witchcraft-log.

Macros

debug	Logs a message at the "debug" level.
enabled	Determines if a message logged at the specified level in the same module would be logged or not.
error	Logs a message at the "error" level.
fatal	Logs a message at the "fatal" level.
info	Logs a message at the "info" level.
log	Logs a message at the specified level.
trace	Logs a message at the "trace" level.
warn	Logs a message at the "warn" level.

Structs

FromStrError	An error parsing a Level or LevelFilter from a string.
Metadata	Metadata of a log record.
MetadataBuilder	A builder for Metadata values.
Record	A log record.
RecordBuilder	A builder for Record values.
SetLoggerError	An error trying to set the logger when one is already installed.

Enums

Level	The verbosity level of a log record.
LevelFilter	A filter for log record verbosity levels.

Traits

Log	A trait encapsulating the operations required of a logger.

Functions

logger	Returns the global logger.
max_level	Returns the current maximum log level.
set_logger	Sets the global logger.
set_max_level	Sets the global maximum log level.