Module fmt

Available on crate features fmt and std only.

A Collector 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 Collect 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.3"

Compiler support: requires rustc 1.63+

Add the following to your executable to initialize the default collector:

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:

• 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 collector instead of using the defaults with the following functions:

Collector

The FmtCollector formats and records tracing events as line-oriented logs. You can create one by calling:

let collector = tracing_subscriber::fmt()
    // ... add configuration
    .finish();

The configuration methods for FmtCollector can be found in fmtBuilder.

Formatters

The output format used by the subscriber and collector in this module is represented by implementing the FormatEvent trait, and can be customized. This module provides a number of formatter implementations:

• format::Full: The default formatter. This emits human-readable, single-line logs for each event that occurs, with the current span context displayed before the formatted representation of the event. See here for sample output.

• format::Compact: A variant of the default formatter, optimized for short line lengths. Fields from the current span context are appended to the fields of the formatted event, and span names are not shown; the verbosity level is abbreviated to a single character. See here for sample output.

• format::Pretty: Emits excessively pretty, multi-line logs, optimized for human readability. This is primarily intended to be used in local development and debugging, or for command-line applications, where automated analysis and compact storage of logs is less of a priority than readability and visual appeal. See here for sample output.

• format::Json: Outputs newline-delimited JSON logs. This is intended for production use with systems where structured logs are consumed as JSON by analysis and viewing tools. The JSON output is not optimized for human readability. See here for sample output.

Customizing Formatters

The formatting of log lines for spans and events is controlled by two traits, FormatEvent and FormatFields. The FormatEvent trait determines the overall formatting of the log line, such as what information from the event’s metadata and span context is included and in what order. The FormatFields trait determines how fields — both the event’s fields and fields on spans — are formatted.

The fmt::format module provides several types which implement these traits, many of which expose additional configuration options to customize their output. The format::Format type implements common configuration used by all the formatters provided in this crate, and can be used as a builder to set specific formatting settings. For example:

use tracing_subscriber::fmt;

// Configure a custom event formatter
let format = fmt::format()
   .with_level(false) // don't include levels in formatted output
   .with_target(false) // don't include targets
   .with_thread_ids(true) // include the thread ID of the current thread
   .with_thread_names(true) // include the name of the current thread
   .compact(); // use the `Compact` formatting style.

// Create a `fmt` collector that uses our custom event format, and set it
// as the default.
tracing_subscriber::fmt()
    .event_format(format)
    .init();

However, if a specific output format is needed, other crates can also implement FormatEvent and FormatFields. See those traits’ documentation for details on how to implement them.

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 Collector

Finally, once you have configured your Collect, you need to configure your executable to use it.

A collector can be installed globally using:

use tracing;
use tracing_subscriber::fmt;

let collector = fmt::Collector::new();

tracing::collect::set_global_default(collector)
    .map_err(|_err| eprintln!("Unable to set global default collector"));
// Note this will only fail if you try to set the global default
// collector multiple times

Composing Subscribers

Composing an EnvFilter Subscribe and a format Subscribe:

use tracing_subscriber::{fmt, EnvFilter};
use tracing_subscriber::subscribe::CollectExt;
use tracing_subscriber::util::SubscriberInitExt;

let fmt_subscriber = fmt::subscriber()
    .with_target(false);
let filter_subscriber = EnvFilter::try_from_default_env()
    .or_else(|_| EnvFilter::try_new("info"))
    .unwrap();

tracing_subscriber::registry()
    .with(filter_subscriber)
    .with(fmt_subscriber)
    .init();

Modules

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

Structs

• Collector
  A Collector that logs formatted representations of tracing events.
• CollectorBuilder
  Configures and constructs Collectors.
• FmtContext
  Provides the current span context to a formatter.
• FormattedFields
  A formatted representation of a span’s fields stored in its extensions.
• Subscriber
  A Subscriber that logs formatted representations of tracing events.
• 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 to a Writer.
• FormatFields
  A type that can format a set of fields to a Writer.
• MakeWriter
  A type that can create io::Write instances.

Functions

• fmt
  Returns a new CollectorBuilder for configuring a formatting collector.
• format
  Returns the default configuration for an event formatter.
• init
  Install a global tracing collector that listens for events and filters based on the value of the RUST_LOG environment variable.
• subscriber
  Returns a new formatting subscriber that can be composed with other subscribers to construct a collector.
• time
  Returns a new SystemTime timestamp provider.
• try_init
  Install a global tracing collector that listens for events and filters based on the value of the RUST_LOG environment variable, if one is not already set.

Type Aliases

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