[−][src]Module tracing_subscriber::fmt

This is supported on 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	`feature="fmt"` Formatters for logging `tracing` events.
time	`feature="fmt"` Formatters for event timestamps.
writer	`feature="fmt"` Abstractions for creating `io::Write` instances.

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 `Layer` that logs formatted representations of `tracing` events.
Subscriber	`feature="fmt"` A `Subscriber` that logs formatted representations of `tracing` events.
SubscriberBuilder	`feature="fmt"` Configures and constructs `Subscriber`s.

Traits

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

Functions

fmt	`feature="fmt"` Returns a new `SubscriberBuilder` for configuring a formatting subscriber.
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 `RUST_LOG` environment variable.
layer	`feature="fmt"` Returns a new formatting layer that can be composed with other layers to construct a `Subscriber`.
time	`feature="fmt"` Returns a new `SystemTime` timestamp provider.
try_init	`feature="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	`feature="fmt"` A `Subscriber` that logs formatted representations of `tracing` events. This type only logs formatted events; it does not perform any filtering.
LayerBuilder	Deprecated`feature="fmt"` A builder for `Layer` that logs formatted representations of `tracing` events and spans.