Crate std_logger[−][src]
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.
This crate provides only a logging implementation. To do actual logging use
the log
crate and it’s various macros.
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 choose:
# Set the log severity to only print log message 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 message 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 choose:
# 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.
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 message you don't need.
$ LOG_LEVEL=trace LOG_TARGET=my_crate::my_module ./my_binary
Note that requests and panics (with target=“panic”) are always logged.
Format
The format follows the logfmt format. For regular messages, printed to standard error, the following format is used:
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"
For requests, logged using the REQUEST_TARGET
target or the request
macro and printed to standard out, the following format is used:
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.
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 is limited to using the std::backtrace
for creating
backtraces, rather than an external library.
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::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 = {}, status = {}, response_time = {:?}", req.url, req.status, req.response_time); }
Macros
request | Logs a request. |
Constants
REQUEST_TARGET | Target for logging requests. |
Functions
init | Initialise the logger. |
try_init | Try to initialise the logger. |