Module tracing_subscriber::fmt[−][src]

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

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

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

Formatters for logging tracing events.

time

Formatters for event timestamps.

writer

Abstractions for creating io::Write instances.

Structs

FmtContext

Provides the current span context to a formatter.

FormattedFields

A formatted representation of a span’s fields stored in its extensions.

Layer

A Layer that logs formatted representations of tracing events.

Subscriber

A Subscriber that logs formatted representations of tracing events.

SubscriberBuilder

Configures and constructs Subscribers.

TestWriter

A writer intended to support libtest’s output capturing for use in unit tests.

Traits

FormatEvent

A type that can format a tracing Event for a fmt::Write.

FormatFields

A type that can format a set of fields to a fmt::Write.

MakeWriter

A type that can create io::Write instances.

Functions

fmt

Returns a new SubscriberBuilder for configuring a formatting subscriber.

format

Returns the default configuration for an [event formatter].

init

Install a global tracing subscriber that listens for events and filters based on the value of the RUST_LOG environment variable.

layer

Returns a new formatting layer that can be composed with other layers to construct a Subscriber.

time

Returns a new SystemTime timestamp provider.

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.

Type Definitions

Formatter

A Subscriber that logs formatted representations of tracing events. This type only logs formatted events; it does not perform any filtering.

LayerBuilderDeprecated

A builder for Layer that logs formatted representations of tracing events and spans.