Module tracing_subscriber::fmt
source · [−]Expand description
A Subscriber
for formatting and logging tracing
data.
Overview
tracing
is a framework for instrumenting Rust programs with context-aware,
structured, event-based diagnostic information. This crate provides an
implementation of the Subscriber
trait that records tracing
’s Event
s
and Span
s by formatting them as text and logging them to stdout.
Usage
First, add this to your Cargo.toml
file:
[dependencies]
tracing-subscriber = "0.3"
Compiler support: requires rustc
1.49+
Add the following to your executable to initialize the default subscriber:
use tracing_subscriber;
tracing_subscriber::fmt::init();
Filtering Events with Environment Variables
The default subscriber installed by init
enables you to filter events
at runtime using environment variables (using the EnvFilter
).
The filter syntax is a superset of the env_logger
syntax.
For example:
- Setting
RUST_LOG=debug
enables allSpan
s andEvent
s set to the log levelDEBUG
or higher - Setting
RUST_LOG=my_crate=trace
enablesSpan
s andEvent
s inmy_crate
at all log levels
Note: This should not be called by libraries. Libraries should use
tracing
to publish tracing
Event
s.
Configuration
You can configure a subscriber instead of using the defaults with the following functions:
Subscriber
The FmtSubscriber
formats and records tracing
events as line-oriented logs.
You can create one by calling:
let subscriber = tracing_subscriber::fmt()
// ... add configuration
.finish();
You can find the configuration methods for FmtSubscriber
in
SubscriberBuilder
.
Formatters
The output format used by the layer and subscriber in this module is
represented by implementing the FormatEvent
trait, and can be
customized. This module provides a number of formatter implementations:
-
format::Full
: The default formatter. This emits human-readable, single-line logs for each event that occurs, with the current span context displayed before the formatted representation of the event. See here for sample output. -
format::Compact
: A variant of the default formatter, optimized for short line lengths. Fields from the current span context are appended to the fields of the formatted event. See here for sample output. -
format::Pretty
: Emits excessively pretty, multi-line logs, optimized for human readability. This is primarily intended to be used in local development and debugging, or for command-line applications, where automated analysis and compact storage of logs is less of a priority than readability and visual appeal. See here for sample output. -
[
format::Json
]: Outputs newline-delimited JSON logs. This is intended for production use with systems where structured logs are consumed as JSON by analysis and viewing tools. The JSON output is not optimized for human readability. See here for sample output.
Customizing Formatters
The formatting of log lines for spans and events is controlled by two
traits, FormatEvent
and FormatFields
. The FormatEvent
trait
determines the overall formatting of the log line, such as what information
from the event’s metadata and span context is included and in what order.
The FormatFields
trait determines how fields — both the event’s
fields and fields on spans — are formatted.
The fmt::format
module provides several types which implement these traits,
many of which expose additional configuration options to customize their
output. The format::Format
type implements common configuration used by
all the formatters provided in this crate, and can be used as a builder to
set specific formatting settings. For example:
use tracing_subscriber::fmt;
// Configure a custom event formatter
let format = fmt::format()
.with_level(false) // don't include levels in formatted output
.with_target(false) // don't include targets
.with_thread_ids(true) // include the thread ID of the current thread
.with_thread_names(true) // include the name of the current thread
.compact(); // use the `Compact` formatting style.
// Create a `fmt` subscriber that uses our custom event format, and set it
// as the default.
tracing_subscriber::fmt()
.event_format(format)
.init();
However, if a specific output format is needed, other crates can
also implement FormatEvent
and FormatFields
. See those traits’
documentation for details on how to implement them.
Filters
If you want to filter the tracing
Events
based on environment
variables, you can use the EnvFilter
as follows:
use tracing_subscriber::EnvFilter;
let filter = EnvFilter::from_default_env();
As mentioned above, the EnvFilter
allows Span
s and Event
s to
be filtered at runtime by setting the RUST_LOG
environment variable.
You can find the other available filter
s in the documentation.
Using Your Subscriber
Finally, once you have configured your Subscriber
, you need to
configure your executable to use it.
A subscriber can be installed globally using:
use tracing;
use tracing_subscriber::FmtSubscriber;
let subscriber = FmtSubscriber::new();
tracing::subscriber::set_global_default(subscriber)
.map_err(|_err| eprintln!("Unable to set global default subscriber"));
// Note this will only fail if you try to set the global default
// subscriber multiple times
Composing Layers
Composing an EnvFilter
Layer
and a format Layer
:
use tracing_subscriber::{fmt, EnvFilter};
use tracing_subscriber::prelude::*;
let fmt_layer = fmt::layer()
.with_target(false);
let filter_layer = EnvFilter::try_from_default_env()
.or_else(|_| EnvFilter::try_new("info"))
.unwrap();
tracing_subscriber::registry()
.with(filter_layer)
.with(fmt_layer)
.init();
Modules
Formatters for logging tracing
events.
Formatters for event timestamps.
Structs
Provides the current span context to a formatter.
A formatted representation of a span’s fields stored in its extensions.
A Subscriber
that logs formatted representations of tracing
events.
Configures and constructs Subscriber
s.
A writer intended to support libtest
’s output capturing for use in unit tests.
Traits
Functions
Returns a new SubscriberBuilder
for configuring a formatting subscriber.
Returns the default configuration for an [event formatter].
Install a global tracing subscriber that listens for events and
filters based on the value of the RUST_LOG
environment variable.
Returns a new formatting layer that can be composed with other layers to
construct a Subscriber
.
Returns a new SystemTime
timestamp provider.
Install a global tracing subscriber that listens for events and
filters based on the value of the RUST_LOG
environment variable,
if one is not already set.
Type Definitions
A Subscriber
that logs formatted representations of tracing
events.
This type only logs formatted events; it does not perform any filtering.