Module tracing_subscriber::fmt

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 Events and Spans by formatting them as text and logging them to stdout.

Usage

First, add this to your Cargo.toml file:

[dependencies]
tracing-subscriber = "0.2"

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 all Spans and Events set to the log level DEBUG or higher
• Setting RUST_LOG=my_crate=trace enables Spans and Events in my_crate at all log levels

Note: This should not be called by libraries. Libraries should use tracing to publish tracing Events.

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:

use tracing_subscriber::FmtSubscriber;

let subscriber = FmtSubscriber::builder()
    // ... add configuration
    .finish();

You can find the configuration methods for FmtSubscriber in fmt::Builder.

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 Spans and Events to be filtered at runtime by setting the RUST_LOG environment variable.

You can find the other available filters 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

Modules

format	Formatters for logging tracing events.
time	Formatters for event timestamps.
writer	Abstractions for creating io::Write instances.

Structs

Builder	Configures and constructs Subscribers.
Context	Represents the Subscriber's view of the current span context to a formatter.
Formatter	A Subscriber that logs formatted representations of tracing events. This type only logs formatted events; it does not perform any filtering.
Subscriber	A Subscriber that logs formatted representations of tracing events.

Traits

FormatEvent	A type that can format a tracing Event for a fmt::Write.
MakeWriter	A type that can create io::Write instances.
NewVisitor	A type that can construct a new field visitor for formatting the fields on a span or event.

Functions

init	Install a global tracing subscriber that listens for events and filters based on the value of the RUST_LOG environment variable.
try_init	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.