Module tracing_subscriber::fmt

This is supported on crate 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 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"

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 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:

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 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

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	fmt Formatters for logging tracing events.
time	fmt Formatters for event timestamps.
writer	fmt Abstractions for creating io::Write instances.

Structs

FmtContext	fmt Provides the current span context to a formatter.
FormattedFields	fmt A formatted representation of a span's fields stored in its extensions.
Layer	fmt A Layer that logs formatted representations of tracing events.
Subscriber	fmt A Subscriber that logs formatted representations of tracing events.
SubscriberBuilder	fmt Configures and constructs Subscribers.
TestWriter	fmt A writer intended to support libtest's output capturing for use in unit tests.

Traits

FormatEvent	fmt A type that can format a tracing Event for a fmt::Write.
FormatFields	fmt A type that can format a set of fields to a fmt::Write.
MakeWriter	fmt A type that can create io::Write instances.

Functions

fmt	fmt Returns a new SubscriberBuilder for configuring a formatting subscriber.
format	fmt Returns the default configuration for an [event formatter].
init	fmt Install a global tracing subscriber that listens for events and filters based on the value of the RUST_LOG environment variable.
layer	fmt Returns a new formatting layer that can be composed with other layers to construct a Subscriber.
time	fmt Returns a new SystemTime timestamp provider.
try_init	fmt 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

Formatter	fmt A Subscriber that logs formatted representations of tracing events. This type only logs formatted events; it does not perform any filtering.
LayerBuilder	Deprecatedfmt A builder for Layer that logs formatted representations of tracing events and spans.