## Motivation
PR #441 increased the minimum supported Rust version, but it only
changed the Azure Pipelines CI configuration, and not the GitHub Actions
one. Additionally, upstream changes to `tower` has broken some of the
examples.
## Solution
This branch bumps the MSRV on GitHub Actions as well, and comments
out examples that depend on code broken upstream.
Additionally, it turns out that — due to Cool Cargo Semver Reasons —
it's more or less impossible to depend on both tokio 0.2.0-alpha.6 *and*
tokio 0.2 release versions. This branch therefore just drops the 0.2.0-alpha.6
support; the next `tracing-futures` will be a breaking change anyway.
Co-authored-by: David Barsky <me@davidbarsky.com>
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
* futures: futures-03 & std-future is the default
Also upgrades futures-03 to the non-preview crate and
renames the `futures` feature to `futures-01`.
Fixes#418
* Update tracing-futures/CHANGELOG.md
Co-Authored-By: Eliza Weisman <eliza@buoyant.io>
* futures: Remove tokio feature from defaults
This branch introduces:
- A registry build atop of https://github.com/hawkw/sharded-slab. Layers
are expected to consume this registry through the traits `SpanData`,
`LookupSpan`, and `LookupMetadata`. Layer-specific data, such as
formatted spans and events, are stored in the `Extensions` typemap. Data
is writable via the `ExtensionsMut` view struct of the typemap. This
enables layers to read and write data that they are specifically
interested in.
- The `tracing_subscriber::fmt::Subscriber` has been re-implemented in
terms of `tracing_subscriber::registry::Registry` and
`tracing_subscriber::fmt::Layer`.
- The event/field formatters have been modified (in a non-backwards
compatible way) to accept a `tracing_subscriber::fmt::FmtContext`. A
similar structure existed in `tracing_subscriber::fmt::Subscriber`, but
it was not publicly exposed.
Resolves#135Resolves#157Resolves#391
Signed-off-by: David Barsky <me@davidbarsky.com>
Coauthored-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
I thought the boxing errors solution implemented in #400 was equivalent
to the enum solution in
f22bae5a2d,
but the current master doesn't actually work to install the global
`LogTracer`.
I can't figure out why the current cargo features don't end up turning
on [this line][1], but I confirmed with the log example in
4511325b29
that it's not currently working.
[1]: https://github.com/tokio-rs/tracing/blob/master/tracing-subscriber/src/fmt/mod.rs#L452-L453
* subscriber: use InitError enum instead of Box
the Boxing solution while using the feature tracing-log/std didn't actually seem to work
* examples: log compatibility
* fix dependencies
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
* fix boxed errors
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
* cargo fmt
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Currently, most crates in `tracing` are configured to deny all compiler
warnings when compiling tests. This means that if the compiler reports
any warnings, the build will fail. This can be an issue when changes are
made locally that introduce warnings (i.e. unused code is added, imports
are no longer needed, etc) and a contributor wishes to test an
incomplete state to ensure their changes are on the right path. With
warnings denied, tests will not run if the project contains any
warnings, so contributors must either fix all warnings or disable the
deny attribute. Disabling the deny attribute when making changes locally
has become a fairly common practice, but it's error-prone: sometimes,
the deny attribute is commented out and then accidentally committed.
## Solution
This branch removes all `#![deny(warnings)]` attributes, in order to
allow code with warnings to compile and be tested locally while changes
are in progress. We already have [a CI job][1] that checks for compiler
warnings by trying to compile `tracing` with `RUSTFLAGS="-Dwarnings"`.
If we make this CI job required rather than allowing it to fail, we'll
still be able to ensure that no code with warnings is merged.
Additionally, I've updated all crates to use the same consistent list of
lints to apply in the `#![warn]` attribute. Previously, some crates
warned on more lints than others, which is not great. I've fixed all the
new warnings produced by the additional lints.
* chore: consistent warnings, don't deny locally
* fix warnings from new attributes
* remove warning that no longer exists on nightly
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This branch prepares for an initial stable release of `tracing-futures`.
I've done some pre-release cleanup and docs work as well as updating
versions.
* futures: improve docs
* futures: pre-release cleanup
* futures: update futures-preview version
* futures: nicer readme/lib docs
* fix breaky path dep
* also fix examples path dep
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Feature Request
### Crates
- `tracing-subscriber`
### Motivation
Currently, the `tracing-subscriber` `FmtSubscriber::default`
implementation defaults to no filtering. This means that all
instrumentation, including extremely verbose `trace`-level diagnostics
from crates like `tokio` are enabled by default.
This is because the subscriber itself does not implement filtering, in
order to allow it to be composed with filters implemented by `Layer`s.
However, defaulting to no filtering at all is definitely a surprising
behavior. I didn't want to conditionally return a different type based
on whether or not filtering was enabled by the `filter` feature flag,
but this is probably not worth the confusion introduced by this
behavior. We should make this more intuitive.
## Solution
This branch changes `tracing-subscriber` to default to enabling
the `INFO` level and above. If the `filter` feature flag is enabled,
users may opt-in to `env_logger`-style filtering. Additionally,
regardless of feature flags, a new `with_max_level` method is
added to the `FmtSubscriber` builder, which takes a `Level` or
`LevelFilter`. `LevelFilter` now implements `Layer` by enabling
any spans and events that are less than or equal to that `Level`.
Fixes: #331Fixes: #332
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
`tracing` currently consists of a large number of crates. The number of
crates has the potential to be quite intimidating to users.
## Solution
This branch makes the following changes:
- Delete `tracing-fmt`. This crate's functionality has already been
moved into `tracing-subscriber`, and a final version has been
published to deprecate the crate & link to the code's new home.
- Delete `tracing-tower-http`, as this functionality is now subsumed
by `tracing-tower`. Since the crate was never published, we do not
need to deprecate it.
- Delete `tracing-slog`. This crate was never implemented, so we can
just remove it from the repository. It can be re-created if we ever
implement `slog` integration.
- Move `tracing-env-logger` into a `tracing-log` module, and feature
flag it. I updated some of the APIs as well.
- Remove deleted crates from documentation.
This makes most of the changes discussed in #308.
Closes#308
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
* tracing: prepare to release 0.1.8
Changed
- Reorganized and improved API documentation (#317)
Removed
- Dev-dependencies on `ansi_term` and `humantime` crates, which were
used only for examples (#316)
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This branch prepares `tracing-log` for an 0.1 release.
Taking this crate out of alpha will allow us to publish
`tracing-subscriber` 0.1, as that crate depends on `tracing-log` & I
don't want to publish an 0.1 that depends on an alpha crate.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Currently, most crates in this repository have `examples` directories
that contain demonstrations of how to use that crate. In many cases,
these examples also use APIs from _other_ crates in this repository ---
for example, the `tracing-subscriber` `FmtSubscriber` is used by many
examples to format the output generated by instrumentation APIs, so that
users can see the generated output.
The disadvantage to this approach is that it requires crates in this
repository to have dev-dependencies on each other. This is problematic
for a few reasons:
* It makes it easy to inadvertently create cyclic dependencies between
`tracing` crates.
* When building a crate that depends on a crate with dev-dependencies,
those dev-dependencies are downloaded and compiled, despite not being
linked into the dependent crate. This means that users depending on a
tracing crate will pull in a larger dependency tree, since the
dev-dependencies used by examples are also downloaded, although they
are not required by the dependent. This makes the tracing crate
appear to be a much larger dependency than it actually is, and can
make users' build times slower.
* Finally, it means that the examples are scattered throughout the
repository. In some cases, the examples demonstrate the functionality
of multiple crates, but only live in one crate's `examples` dir. This
can hurt the discoverability of the examples, especially for new
users.
## Solution
This branch moves all the examples out of individual crates and into a
new `examples` crate (which is otherwise empty and cannot be published
to crates.io). The `examples` crate is part of the root `tracing`
workspace, so it's still possible to `cargo run --example WHATEVER`.
Similarly, `cargo test --all` will still build the examples.
All dev-dependencies which were only required by examples and not tests
have been removed, which has a drastic impact on the dependency
footprint of some crates.
Finally, I've added a README to the `examples` crate, listing the
available examples and what functionality they demonstrate.
Refs: #315, #308
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
See #95
This branch renames everything from `tokio-trace` to `tracing`.
Unlike PR #98, the nursery crates still depend on the crates.io
versions of `tokio-trace` and `tokio-trace-core`, but renamed
to `tracing`/`tracing-core` in `Cargo.toml`. We can update the
nursery crates to depend on local path dependencies in a
subsequent PR, as that will require making code changes to the
nursery crates.
This branch _also_ updates the minimum Rust version to 1.34.0,
to the shock and horror of the millions of `tracing` users still
on Rust 1.26.0. This was necessary in order to allow renaming
crates in `Cargo.toml`, and to resolve that not using the `dyn`
keyword is now a warning on nightly.
Closes#98Closes#95
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Currently, the primary way to use a span is to use `.enter` and pass a
closure to be executed under the span. While that is convenient in many
settings, it also comes with two decently inconvenient drawbacks:
- It breaks control flow statements like `return`, `?`, `break`, and
`continue`
- It require re-indenting a potentially large chunk of code if you wish
it to appear under a span
## Solution
This branch changes the `Span::enter` function to return a scope guard
that exits the span when dropped, as in:
```rust
let guard = span.enter();
// code here is within the span
drop(guard);
// code here is no longer within the span
```
The method previously called `enter`, which takes a closure and
executes it in the span's context, is now called `Span::in_scope`, and
was reimplemented on top of the new `enter` method.
This is a breaking change to `tokio-trace` that will be part of the
upcoming 0.2 release.
Closes#1075
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
The `Span::enter` function previously required an `&mut` reference to
enter a span. This is a relic of an earlier design where span closure
logic was determined by dropping an inner span component, and is no
longer strictly necessary.
Requiring `&mut self` to enter a span leads to awkward patterns in cases
when a user wishes to enter a span and then call methods on the span
(such as recording field values). For example, we cannot say
```rust
let mut span = span!("foo", bar);
span.enter(|| {
span.record("bar" &false);
});
```
since the span is mutably borrowed by `enter`. Instead, we must clone
the span, like so:
```rust
let mut span = span!("foo", bar);
span.clone().enter(|| {
span.record("bar" &false);
});
```
Having to clone the span is somewhat less ergonomic, and it has
performance disadvantages as well: cloning a `Span` will clone the
span's `Dispatch` handle, requiring an `Arc` bump, as well as calling
the `Subscriber`'s `clone_span` and `drop_span` functions. If we can
enter spans without a mutable borrow, we don't have to update any of
these ref counts.
The other reason we may wish to require mutable borrows to enter a span
is if we want to disallow entering a span multiple times before exiting
it. However, it is trivially possible to re-enter a span on the same
thread regardless, by cloning the span and entering it twice. Besides,
there may be a valuable semantic meaning in entering a span from inside
itself, such as when a function is called recursively, so disallowing
this is not a goal.
## Solution
This branch rewrites the `Span::enter`, `Span::record`, and
`Span::record_all` functions to no longer require mutable borrows.
In the case of `record` and `record_all`, this was trivial, as borrowing
mutably was not actually *necessary* for those functions. For `enter`,
the `Entered` guard type was reworked to consist of an `&'a Inner`
rather than an `Inner`, so it is no longer necessary to `take` the
span's `Inner`.
## Notes
In addition to allowing spans to be entered without mutable borrows,
`Entered` was changed to exit the span automatically when the guard is
dropped, so we may now observe correct span exits even when unwinding.
Furthermore, this allows us to simplify the `enter` function a bit,
leading to a minor performance improvement when entering spans.
Before:
```
test enter_span ... bench: 13 ns/iter (+/- 1)
```
...and after:
```
test enter_span ... bench: 3 ns/iter (+/- 1)
```
Note that this branch also contains a change to make the
`subscriber::enter_span` benchmark more accurate. Previously, this
benchmark constructed a new span inside of `b.iter(|| {...})`. This
means that the benchmark was measuring not only the time taken to enter
a span, but the time taken to construct a `Span` handle as well.
However, we already have benchmarks for span construction, and the
intention of this particular benchmark was to measure the overhead of
constructing a span.
I've updated the benchmark by moving the span construction out of the
`iter` closure. Now, the span is constructed a single time and entered
on every iteration. This allows us to measure only the overhead of
actually entering a span. The "before" benchmark numbers above were
recorded after backporting this change to master, so they are "fair" to
the previous implementation. Prior to this change the benchmark took
approximately 53 ns.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Was determined that having the span! macro default to the TRACE level is
probably not ideal (see discussion on #952).
Closes#1013
## Solution
Remove default trace level and make log lvl mandatory on span! macro,
and add the respective `trace_span!`, `debug_span!`, `info_span!`,
`warn_span!` and `error_span!` macros that behave as span! macro, but
with defined log levels
## Notes
I think this is it, also removed some captures that were repeated, and
some testcases that also seemed repeated after adding the mandatory log
level, but please review it, if more tests or examples are needed happy
to provide (tried to find a way to get the generated macros log level,
but didn't find one, if there is a way i can add tests to assert that
the generated macro has the matching log level ). thanks
## Motivation
`tokio-trace` currently offers a strategy for compatibility with the
`log` crate: its macros can be dropped in as a replacement for `log`'s
macros, and a subscriber can be used that translates trace events to log
records. However, this requires the application to be aware of
`tokio-trace` and manually set up this subscriber.
Many libraries currently emit `log` records, and would like to be able
to emit `tokio-trace` instrumentation instead. The `tokio` runtimes are
one such example. However, with the current log compatibility strategy,
replacing existing logging with trace instrumentation would break
`tokio`'s logs for any downstream user which is using only `log` and not
`tokio-trace`. It is desirable for libraries to have the option to emit
both `log` _and_ `tokio-trace` diagnostics from the same instrumentation
points.
## Solution
This branch adds a `log` feature flag to the `tokio-trace` crate, which
when set, causes `tokio-trace` instrumentation to emit log records as well
as `tokio-trace` instrumentation.
## Notes
In order to allow spans to log their names when they are entered and
exited even when the span is disabled, this branch adds an
`&'static Metadata` to the `Span` type. This was previously stored in
the `Inner` type and was thus only present when the span was enabled.
This makes disabled spans one word longer, but enabled spans remain
the same size.
Fixes: #949
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
* trace-core: Pass dispatcher by ref to `dispatcher::with_default`
As requested by @carllerche in https://github.com/tokio-rs/tokio/pull/966#discussion_r264380005, this branch changes the
`dispatcher::with_default` function in `tokio-trace-core` to take the
dispatcher by ref and perform the clone internally. This makes this
function more consistant with other `with_default` functions in other
crates.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
* trace: Don't set the default dispatcher on entering a span
Setting the default dispatcher on span entry is a relic of when spans
tracked their parent's ID. At that time, it was necessary to ensure that
any spans created inside a span were observed by the same subscriber
that originally provided the entered span with an ID, as otherwise, new
spans would be created with parent IDs that did not originate from that
subscriber.
Now that spans don't track their parent ID, this is no longer necessary.
However, removing this behavior does mean that if a span is entered
outside of the subscriber context it was created in, any subsequent
spans will be observed by the current default subscriber and thus will
not be part of the original span's trace tree. Since subscribers are not
expected to change frequently, and spans are not expected to move
between them, this is likely acceptable.
I've removed the tests for the old behavior.
Note that this change improves the performance of span entry/exit fairly
significantly. Here are the results of running a benchmark that enters
a span, does nothing, and immediately exits it, before this change:
```
test enter_span ... bench: 93 ns/iter (+/- 14)
```
...and after:
```
test enter_span ... bench: 51 ns/iter (+/- 9)
```
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This branch makes a handful of `tokio-trace-core` API improvements, mostly
around naming. In particular:
* Rename `dispatcher::with` to `dispatcher::get_default`
* Rename `Event::observe` to `Event::dispatch`
* Make `field::ValidLen` trait private
Closes#948Closes#960
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This branch changes the `Subscriber::record` method to take a new
arguments struct, `span::Record`. The `field::Record` trait was renamed
to `field::Visit` to prevent name conflicts.
In addition, the `ValueSet::is_empty`, `ValueSet::contains`, and
`ValueSet::record` methods were made crate-private, as they are exposed
on the `Attributes` and `Record` types.
Signed-off-by: Eliza Weisman <elzia@buoyant.io>
This branch allows users of `tokio-trace` to explicitly set a span's
parent, or indicate that a span should be a new root of its own trace
tree. A `parent: ` key has been added to the `span!` macros. When a span
is provided, that span will be set as the parent, while `parent: None`
will result in a new root span. No `parent:` key results in the current
behaviour.
A new type, `span::Attributes`, was added to `tokio-trace-core` to act
as an arguments struct for the `Subscriber::new_span` method. This will
allow future fields to be added without causing breaking API changes.
The `Attributes` struct currently contains the new span's metadata,
`ValueSet`, and parent.
Finally, the `span::Span` type in `-core` was renamed to `span::Id`, for
consistency with `tokio-trace` and to differentiate it from
`span::Attributes`. This name was chosen primarily due to precedent in
other tracing systems.
Closes#920
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
<!-- Thank you for your Pull Request. Please provide a description above
and review the requirements below.
Bug fixes and new features should include tests.
Contributors guide:
https://github.com/tokio-rs/tokio/blob/master/CONTRIBUTING.md -->
## Motivation
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. Currently, none
of the available logging frameworks or libraries in Rust offer the
ability to trace logical paths through a futures-based program.
There also are complementary goals that can be accomplished with such a
system. For example, metrics / instrumentation can be tracked by
observing emitted events, or trace data can be exported to a distributed
tracing or event processing system.
In addition, it can often be useful to generate this diagnostic data in
a structured manner that can be consumed programmatically. While prior
art for structured logging in Rust exists, it is not currently
standardized, and is not "Tokio-friendly".
## Solution
This branch adds a new library to the tokio project, `tokio-trace`.
`tokio-trace` 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 `tokio-trace` 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, `tokio-trace` spans are
*structured*, with the ability to record typed data as well as textual
messages.
The `tokio-trace-core` crate contains the core primitives for this
system, which are expected to remain stable, while `tokio-trace` crate
provides a more "batteries-included" API. In particular, it provides
macros which are a superset of the `log` crate's `error!`, `warn!`,
`info!`, `debug!`, and `trace!` macros, allowing users to begin the
process of adopting `tokio-trace` by performing a drop-in replacement.
## Notes
Work on this project had previously been carried out in the
[tokio-trace-prototype] repository. In addition to the `tokio-trace` and
`tokio-trace-core` crates, the `tokio-trace-prototype` repo also
contains prototypes or sketches of adapter, compatibility, and utility
crates which provide useful functionality for `tokio-trace`, but these
crates are not yet ready for a release. When this branch is merged, that
repository will be archived, and the remaining unstable crates will be
moved to a new `tokio-trace-nursery` repository. Remaining issues on the
`tokio-trace-prototype` repo will be moved to the appropriate new repo.
The crates added in this branch are not _identical_ to the current head
of the `tokio-trace-prototype` repo, as I did some final clean-up and docs
polish in this branch prior to merging this PR.
[tokio-trace-prototype]: https://github.com/hawkw/tokio-trace-prototypeCloses: #561
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
