[−][src]Module tracing_subscriber::fmt
feature="fmt"
only.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.2"
Compiler support: requires rustc 1.39+
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 fmtBuilder
.
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
format | feature="fmt" Formatters for logging |
time | feature="fmt" Formatters for event timestamps. |
writer | feature="fmt" Abstractions for creating |
Structs
FmtContext | feature="fmt" Provides the current span context to a formatter. |
FormattedFields | feature="fmt" A formatted representation of a span's fields stored in its extensions. |
Layer | feature="fmt" A |
Subscriber | feature="fmt" A |
SubscriberBuilder | feature="fmt" Configures and constructs |
Traits
FormatEvent | feature="fmt" A type that can format a tracing |
FormatFields | feature="fmt" A type that can format a set of fields to a |
MakeWriter | feature="fmt" A type that can create |
Functions
fmt | feature="fmt" Returns a new |
format | feature="fmt" Returns the default configuration for an [event formatter]. |
init | feature="fmt" Install a global tracing subscriber that listens for events and
filters based on the value of the |
layer | feature="fmt" Returns a new formatting layer that can be composed with other layers to
construct a |
time | feature="fmt" Returns a new |
try_init | feature="fmt" Install a global tracing subscriber that listens for events and
filters based on the value of the |
Type Definitions
Formatter | feature="fmt" A |
LayerBuilder | Deprecatedfeature="fmt" A builder for |