🛈 Note: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem.

For the release documentation, please see docs.rs, instead.

logo
Expand description

Futures compatibility for tracing.

Overview

tracing is a framework for instrumenting Rust programs to collect structured, event-based diagnostic information. This crate provides utilities for using tracing to instrument asynchronous code written using futures and async/await.

The crate provides the following traits:

  • Instrument allows a tracing span to be attached to a future, sink, stream, or executor.

  • WithCollector allows a tracing collector to be attached to a future, sink, stream, or executor.

Compiler support: requires rustc 1.49+

Feature flags

This crate provides a number of feature flags that enable compatibility features with other crates in the asynchronous ecosystem:

  • tokio: Enables compatibility with the tokio crate, including Instrument and WithCollector implementations for tokio::executor::Executor, tokio::runtime::Runtime, and tokio::runtime::current_thread. Enabled by default.

  • tokio-executor: Enables compatibility with the tokio-executor crate, including Instrument and WithCollector implementations for types implementing tokio_executor::Executor. This is intended primarily for use in crates which depend on tokio-executor rather than tokio; in general the tokio feature should be used instead.

  • std-future: Enables compatibility with std::future::Future.

  • futures-01: Enables compatibility with version 0.1.x of the futures crate.

  • futures-03: Enables compatibility with version 0.3.x of the futures crate’s Spawn and LocalSpawn traits.

  • tokio-alpha: Enables compatibility with tokio 0.2’s alpha releases, including the tokio 0.2 Executor and TypedExecutor traits.

  • std: Depend on the Rust standard library.

    no_std users may disable this feature with default-features = false:

    [dependencies]
    tracing-futures = { version = "0.2.3", default-features = false }

The tokio, std-future and std features are enabled by default.

Supported Rust Versions

Tracing is built against the latest stable release. The minimum supported version is 1.49. The current Tracing version is not guaranteed to build on Rust versions earlier than the minimum supported version.

Tracing follows the same compiler support policies as the rest of the Tokio project. The current stable Rust compiler and the three most recent minor versions before it will always be supported. For example, if the current stable compiler version is 1.45, the minimum supported version will not be increased past 1.42, three minor versions prior. Increasing the minimum supported compiler version is not considered a semver breaking change as long as doing so complies with this policy.

Modules

Implementations for Instrumented future executors.

Structs

A future, stream, sink, or executor that has been instrumented with a tracing span.
A future, stream, sink, or executor that has been instrumented with a tracing subscriber.

Traits

Extension trait allowing futures, streams, sinks, and executors to be instrumented with a tracing span.
Extension trait allowing futures, streams, and sinks to be instrumented with a tracing collector.