| dispatcher.rs |
|
5891 |
| field.rs |
|
6907 |
| instrument.rs |
|
11553 |
| level_filters.rs |
Trace verbosity level filtering.
# Compile time filters
Trace verbosity levels can be statically disabled at compile time via Cargo
features, similar to the [`log` crate]. Trace instrumentation at disabled
levels will be skipped and will not even be present in the resulting binary
unless the verbosity level is specified dynamically. This level is
configured separately for release and debug builds. The features are:
* `max_level_off`
* `max_level_error`
* `max_level_warn`
* `max_level_info`
* `max_level_debug`
* `max_level_trace`
* `release_max_level_off`
* `release_max_level_error`
* `release_max_level_warn`
* `release_max_level_info`
* `release_max_level_debug`
* `release_max_level_trace`
These features control the value of the `STATIC_MAX_LEVEL` constant. The
instrumentation macros macros check this value before recording an event or
constructing a span. By default, no levels are disabled.
For example, a crate can disable trace level instrumentation in debug builds
and trace, debug, and info level instrumentation in release builds with the
following configuration:
```toml
[dependencies]
tracing = { version = "0.1", features = ["max_level_debug", "release_max_level_warn"] }
```
## Notes
Please note that `tracing`'s static max level features do *not* control the
[`log`] records that may be emitted when [`tracing`'s "log" feature flag][f] is
enabled. This is to allow `tracing` to be disabled entirely at compile time
while still emitting `log` records --- such as when a library using
`tracing` is used by an application using `log` that doesn't want to
generate any `tracing`-related code, but does want to collect `log` records.
This means that if the "log" feature is in use, some code may be generated
for `log` records emitted by disabled `tracing` events. If this is not
desirable, `log` records may be disabled separately using [`log`'s static
max level features][`log` crate].
[`log`]: https://docs.rs/log/
[`log` crate]: https://docs.rs/log/latest/log/#compile-time-filters
[f]: https://docs.rs/tracing/latest/tracing/#emitting-log-records |
4398 |
| lib.rs |
A scoped, structured logging and diagnostics system.
# 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.
*Compiler support: [requires `rustc` 1.49+][msrv]*
[msrv]: #supported-rust-versions
# Core Concepts
The core of `tracing`'s API is composed of _spans_, _events_ and
_subscribers_. We'll cover these in turn.
## Spans
To record the flow of execution through a program, `tracing` introduces the
concept of [spans]. Unlike a log line that represents a _moment in
time_, a span represents a _period of time_ with a beginning and an end. When a
program begins executing in a context or performing a unit of work, it
_enters_ that context's span, and when it stops executing in that context,
it _exits_ the span. The span in which a thread is currently executing is
referred to as that thread's _current_ span.
For example:
```
use tracing::{span, Level};
# fn main() {
let span = span!(Level::TRACE, "my_span");
// `enter` returns a RAII guard which, when dropped, exits the span. this
// indicates that we are in the span for the current lexical scope.
let _enter = span.enter();
// perform some work in the context of `my_span`...
# }
```
The [`span` module][span]'s documentation provides further details on how to
use spans.
<div class="example-wrap" style="display:inline-block"><pre class="compile_fail" style="white-space:normal;font:inherit;">
**Warning**: In asynchronous code that uses async/await syntax,
`Span::enter` may produce incorrect traces if the returned drop
guard is held across an await point. See
[the method documentation][Span#in-asynchronous-code] for details.
</pre></div>
## Events
An [`Event`] represents a _moment_ in time. It signifies something that
happened while a trace was being recorded. `Event`s are comparable to the log
records emitted by unstructured logging code, but unlike a typical log line,
an `Event` may occur within the context of a span.
For example:
```
use tracing::{event, span, Level};
# fn main() {
// records an event outside of any span context:
event!(Level::INFO, "something happened");
let span = span!(Level::INFO, "my_span");
let _guard = span.enter();
// records an event within "my_span".
event!(Level::DEBUG, "something happened inside my_span");
# }
```
In general, 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.
The [`Event` struct][`Event`] documentation provides further details on using
events.
## Subscribers
As `Span`s and `Event`s occur, they are recorded or aggregated by
implementations of the [`Subscriber`] trait. `Subscriber`s are notified
when an `Event` takes place and when a `Span` is entered or exited. These
notifications are represented by the following `Subscriber` trait methods:
+ [`event`][Subscriber::event], called when an `Event` takes place,
+ [`enter`], called when execution enters a `Span`,
+ [`exit`], called when execution exits a `Span`
In addition, subscribers may implement the [`enabled`] function to _filter_
the notifications they receive based on [metadata] describing each `Span`
or `Event`. If a call to `Subscriber::enabled` returns `false` for a given
set of metadata, that `Subscriber` will *not* be notified about the
corresponding `Span` or `Event`. For performance reasons, if no currently
active subscribers express interest in a given set of metadata by returning
`true`, then the corresponding `Span` or `Event` will never be constructed.
# Usage
First, add this to your `Cargo.toml`:
```toml
[dependencies]
tracing = "0.1"
```
## Recording Spans and Events |
45419 |
| macros.rs |
|
77026 |
| span.rs |
|
57303 |
| stdlib.rs |
Re-exports either the Rust `std` library or `core` and `alloc` when `std` is
disabled.
`crate::stdlib::...` should be used rather than `std::` when adding code that
will be available with the standard library disabled.
Note that this module is called `stdlib` rather than `std`, as Rust 1.34.0
does not permit redefining the name `stdlib` (although this works on the
latest stable Rust). |
1699 |
| subscriber.rs |
Collects and records trace data. |
2337 |