Crate std_logger

source ·
Expand description

A crate that holds a logging implementation that logs to standard error and standard out. It uses standard error for all regular messages and standard out for requests. To initialise the logger use Config.

This crate provides only a logging implementation. To do actual logging use the log crate and it’s various macros.

§Supported Formats

This crate supports the three following formats:

§Logfmt

For regular messages, printed to standard error, Logfmt looks like the following:

ts="YYYY-MM-DDTHH:MM:SS.MICROSZ" lvl="$LOG_LEVEL" msg="$message" target="$target" module="$module"

For example:

ts="2018-03-24T13:48:28.820588Z" lvl="ERROR" msg="my error message" target="my_module" module="my_module"

Requests or access messages, logged using the REQUEST_TARGET target or the request macro, are printed to standard out using following format:

ts="YYYY-MM-DDTHH:MM:SS.MICROSZ" lvl="INFO" msg="$message" target="request" module="$module"

For example:

ts="2018-03-24T13:30:28.820588Z" lvl="INFO" msg="my request message" target="request" module="my_module"

Note: the timestamp is not printed when the timestamp feature is not enabled, this feature is enabled by default, see Timestamp feature below.

§JSON (NDJSON)

Formatting using JSON uses one object per limit, which looks like the following:

{"timestamp":"YYYY-MM-DDTHH:MM:SS.MICROSZ","level":"$LOG_LEVEL","message":"$message","target":"$module","module":"$module"}

For example:

{"timestamp":"2018-03-24T13:48:28.820588Z","level":"ERROR","message":"my error message","target":"my_module","module":"my_module"}

Note: the timestamp is not printed when the timestamp feature is not enabled, this feature is enabled by default, see Timestamp feature below.

§Gcloud (GCP JSON)

Google Cloud Platform structured logging using JSON, or just gcloud for short, uses JSON for messages. Regular messages are printed to standard error and look like the following:

{"timestamp":"YYYY-MM-DDTHH:MM:SS.MICROSZ","severity":"$LOG_LEVEL","message":"$message","target":"$module","module":"$module"}

For example:

{"timestamp":"2018-03-24T13:48:28.820588Z","severity":"ERROR","message":"my error message","target":"my_module","module":"my_module"}

Note: the timestamp is not printed when the timestamp feature is not enabled, this feature is enabled by default, see Timestamp feature below.

The format for requests looks the same, but are logged to standard out. There are some things to note that are special for the gcloud format:

  • Panics are logged using the CRITICAL severity instead of ERROR.
  • When debug logging is enabled sourceLocation is added with the file and line information to all logs, if the source information is provided.

§Setting severity

You can use various environment variables to change the severity (log level) of the messages to actually log and which to ignore.

LOG and LOG_LEVEL can be used to set the severity to a specific value, see the log’s package LevelFilter type for available values.

## In your shell of your choice:

## Set the log severity to only print log messages with info severity or
## higher, trace and debug messages won't be printed anymore.
$ LOG=info ./my_binary

## Set the log severity to only print log messages with warning severity or
## higher, informational (or lower severity) messages won't be printed
## anymore.
$ LOG=warn ./my_binary

Alternatively setting the TRACE variable (e.g. TRACE=1) sets the severity to the trace, meaning it will log everything. Setting DEBUG will set the severity to debug.

## In your shell of your choice:

## Enables trace logging.
$ TRACE=1 ./my_binary

## Enables debug logging.
$ DEBUG=1 ./my_binary

If none of these environment variables are found it will default to an information severity.

In addition to these runtime filters the log crate provides compile time filters which allows you to filter log messages at compile time.

§Logging requests

To log requests a special target is provided: REQUEST_TARGET and a special macro: request. This will cause the message to be logged to standard out, rather then standard error. This allows for separate processing of error messages and request logs.

use std_logger::request;

request!("Got a request!");

§Limiting logging targets

Sometimes it’s useful to only log messages related to a specific target, for example when debugging a single function you might want only see messages from the module the function is in. This can be achieved by using the LOG_TARGET environment variable.

## In your shell of choose:

## Only log messages from your crate.
$ LOG_TARGET=my_crate ./my_binary

## Only log messages from the `my_module` module in your crate.
$ LOG_TARGET=my_crate::my_module ./my_binary

## Multiple log targets are also supported by separating the values by a comma.
$ LOG_TARGET=my_crate::my_module,my_crate::my_other_module ./my_binary

## Very useful in combination with trace severity to get all messages you
## want, but filter out the messages for crates you're not interested in.
$ LOG_LEVEL=trace LOG_TARGET=my_crate::my_module ./my_binary

Note that requests and panics (with target=“panic”) are always logged.

§Crate features

This crate has three features:

  • timestamp, enabled by default.
  • log-panic, enabled by default.
  • nightly, disabled by default.

§Timestamp feature

The timestamp feature adds a timestamp in front of every message. It uses the format defined in RFC3339 with 6 digit microsecond precision, e.g. 2018-03-24T13:48:48.063934Z. The timestamp is always logged in UTC.

§Notes

This feature uses SystemTime as time source, which is not monotonic. This means that a log message created after an earlier log message can have a timestamp before the earlier created log message.

§Log-panic feature

The log-panic feature will log all panics using the error severity, rather then using the default panic handler. It will log the panic message as well as the location and a backtrace, see the log output below for an example (this example doesn’t include a timestamp).

lvl="ERROR" msg="thread 'main' panicked at 'oops', examples/panic.rs:24" target="panic" module="" backtrace="
stack backtrace:
   0:        0x106ba8f74 - backtrace::backtrace::trace<closure>
                        at backtrace-0.3.2/src/backtrace/mod.rs:42
   1:        0x106ba49af - backtrace::capture::Backtrace::new::h54d7cfa8f40c5b43
                        at backtrace-0.3.2/src/capture.rs:64
   2:        0x106b9f4e6 - log_panics::init::{{closure}}
                        at log-panics-1.2.0/src/lib.rs:52
   3:        0x106bc6951 - std::panicking::rust_panic_with_hook::h6c19f9ba35264287
                        at src/libstd/panicking.rs:612
   4:        0x106b93146 - std::panicking::begin_panic<&str>
                        at src/libstd/panicking.rs:572
   5:        0x106b93bf1 - panic::main
                        at examples/panic.rs:24
   6:        0x106bc751c - __rust_maybe_catch_panic
                        at src/libpanic_unwind/lib.rs:98
   7:        0x106bc6c08 - std::rt::lang_start::h6f338c4ae2d58bbe
                        at src/libstd/rt.rs:61
   8:        0x106b93c29 - main
"

If the timestamp feature is enable the first line of the message will be prefixed with a timestamp as described in the Timestamp feature.

§Nightly feature

Enabling this feature enables the crate to use unstable (i.e. nightly-only) features from the compiler and standard library.

Currently this enables nothing.

§Examples

use log::info;
use std_logger::request;

fn main() {
    // First thing we need to do is initialise the logger before anything
    // else.
    std_logger::Config::logfmt().init();

    // Now we can start logging!
    info!("Our application started!");

    // Do useful stuff, like starting a HTTP server.
}

/// This our example request handler, just pretend it gets called with a
/// request.
fn log_handler(req: Request) {
    // This will be logged to standard out, rather then standard error.
    request!(
        url = req.url,
        status = req.status,
        response_time:? = req.response_time;
        "HTTP request"
    );
}

Macros§

Structs§

  • Config
    Configuration of the logger.

Constants§