tracing
Application-level tracing for Rust.
Overview
tracing
is a framework for instrumenting Rust programs to collect
structured, event-based diagnostic information.
In asynchronous systems like Tokio, interpreting traditional log messages can
often be quite challenging. Since individual tasks are multiplexed on the same
thread, associated events and log lines are intermixed making it difficult to
trace the logic flow. tracing
expands upon logging-style diagnostics by
allowing libraries and applications to record structured events with additional
information about temporality and causality — unlike a log message, a span
in tracing
has a beginning and end time, may be entered and exited by the
flow of execution, and may exist within a nested tree of similar spans. In
addition, tracing
spans are structured, with the ability to record typed
data as well as textual messages.
The tracing
crate provides the APIs necessary for instrumenting libraries
and applications to emit trace data.
Usage
First, add this to your Cargo.toml
:
[]
= "0.1"
Next, add this to your crate:
extern crate tracing;
This crate provides macros for creating Span
s and Event
s, which represent
periods of time and momentary events within the execution of a program,
respectively.
As a rule of thumb, spans should be used to represent discrete units of work (e.g., a given request's lifetime in a server) or periods of time spent in a given context (e.g., time spent interacting with an instance of an external system, such as a database). In contrast, events should be used to represent points in time within a span — a request returned with a given status code, n new items were taken from a queue, and so on.
Span
s are constructed using the span!
macro, and then entered
to indicate that some code takes place within the context of that Span
:
// Construct a new span named "my span".
let mut span = span!;
span.in_scope;
// Dropping the span will close it, indicating that it has ended.
The Event
type represent an event that occurs instantaneously, and is
essentially a Span
that cannot be entered. They are created using the event!
macro:
use Level;
event!;
Users of the log
crate should note that tracing
exposes a set of macros for
creating Event
s (trace!
, debug!
, info!
, warn!
, and error!
) which may
be invoked with the same syntax as the similarly-named macros from the log
crate. Often, the process of converting a project to use tracing
can begin
with a simple drop-in replacement.
Let's consider the log
crate's yak-shaving example:
extern crate tracing;
use field;
You can find examples showing how to use this crate in the examples directory.
In libraries
Libraries should link only to the tracing
crate, and use the provided
macros to record whatever information will be useful to downstream consumers.
In executables
In order to record trace events, executables have to use a Subscriber
implementation compatible with tracing
. A Subscriber
implements a way of
collecting trace data, such as by logging it to standard output.
There currently aren't too many subscribers to choose from. The best one to use right now
is probably tracing-fmt
, which logs to the terminal.
The simplest way to use a subscriber is to call the set_global_default
function:
extern crate tracing;
let my_subscriber = new;
set_global_default.expect;
This subscriber will be used as the default in all threads for the remainder of the duration
of the program, similar to how loggers work in the log
crate.
Note: Libraries should NOT call set_global_default()
! That will cause conflicts when
executables try to set the default later.
In addition, you can locally override the default subscriber, using the tokio
pattern
of executing code in a context. For example:
extern crate tracing;
let my_subscriber = new;
with_default
This approach allows trace data to be collected by multiple subscribers within different contexts in the program. Note that the override only applies to the currently executing thread; other threads will not see the change from with_default.
Any trace events generated outside the context of a subscriber will not be collected.
The executable itself may use the tracing
crate to instrument itself as
well.
The tracing-nursery
repository contains less stable crates designed to
be used with the tracing
ecosystem. It includes a collection of
Subscriber
implementations, as well as utility and adapter crates.
License
This project is licensed under the MIT license.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Tokio by you, shall be licensed as MIT, without any additional terms or conditions.