# 0.1.9 (January 10, 2020)
### Added
- API docs now show what feature flags are required to enable each item (#523)
### Fixed
- A panic when the current default subscriber subscriber calls
`dispatcher::with_default` as it is being dropped (#522)
- Incorrect documentation for `Subscriber::drop_span` (#524)
Starts on #440.
This branch adds `doc_cfg` attributes to `tracing` and `tracing-core`,
when a `docsrs` cfg flag is passed to rustdoc. It also adds
docs.rs crate metadata to configure docs.rs to set that flag, and adds
it to the Netlify config as well.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Co-authored-by: Jane Lusby <jlusby42@gmail.com>
The docs for `drop_span` incorrectly state that the method is
"soft-deprecated", when it's actually...normal deprecated. The RustDoc
says that "using this method won't cause a compilation warning", but
this is incorrect.
This branch updates the doc comment.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
With this change we replace DefaultGuard's drop implementation with a
version that no longer drops the previous dispatch object while the
comprising RefCell is borrowed mutably. In issue #521 we have seen how
this can back fire and result in a panic.
This patch is based on a suggestion by @hawkw (thanks for the quick
feedback!).
Fixes: #521
This is a follow up PR for #477 that runs clippy on CI.
* Switch from hecrj/setup-rust-action to actions-rs/toolchain
* Fix remaining clippy lints
* Switch to minimal rustup profile
* Replace warning step with clippy
* Remove #![feature(async_await)]
This PR fixes all reported clippy lints. In most cases I have made the
suggested changes. In a few cases (e.g., `blacklisted_name` and
`cognitive_complexity`) I've just silenced the warning.
I can make stylistic changes or discard some of the lint fixes if
preferred.
Added
- `Default` impl for `Dispatch` (#411)
Fixed
- Removed duplicate `lazy_static` dependencies (#424)
- Fixed no-std dependencies being enabled even when `std` feature flag
is set (#424)
- Broken link to `Metadata` in `Event` docs (#461)
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This branch updates all the README links and badges. In particular, it:
* Changes build status badges to GitHub Actions, since we've turned off
the Azure Pipelines CI build,
* Removes Gitter links, since nobody is on Gitter these days and we
probably don't want to point new users to an empty chat room,
* Make Discord links "actually work"
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Following the suggested fix on #365:
https://github.com/tokio-rs/tracing/issues/365#issuecomment-537743811
tracing-core's use of `spin` is feature-gated. `lazy_static` is vendored
for either feature but I've modified it to respect our feature flags.
I've also removed doc comments that no longer compile and suppressed a
couple of warnings with the lints that are now being applied.
At this point
* Including this in another project with std `lazy_static`
works
* Tracing unit tests pass both with and without
`--no-default-features`
Fixes#365
* core: vendor lazy_static and spin for no_std support
* core: fmt vendored code
* core: trim down vendored spin, reduce visibility and addresss warnings
* core: limit vendored lazy_static for use only with no_std, fix warnings
* core: update paths to now-vendored no_std libs
* tracing: use spin::Once re-exported from tracing-core instead of crate
* core: remove ineffectual doc(hidden)
* core: refmt stdlib module
* core: bump to 0.1.8 to expose export of vendored spin::Once to tracing
## Motivation
As outlined in #172, we can improve the use of default dispatch by
implementing `Default` to create `Dispatch::default`, thus making
the default dispatcher easier to use.
## Solution
This PR adds an implementation of `Default` trait from the standard
library that calls `get_default` and returns a clone of the default
dispatcher.
Closes#172
Signed-off-by: Adityo Pratomo <adityo@tetrate.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>
### Added
- Added `dispatcher::set_default` API which returns a drop guard (#388)
### Fixed
- Added missing `Value` impl for `u8` (#392)
- Broken links in docs.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
u8 had been forgotten from the list of automatically generated
implementations for the Value Trait. See bug report #389
## Solution
Added u8 to the list of automatically generated implementations for the
Value Trait.
Fixes: #389
## Motivation
As discussed in #383 , adds the new `set_default` method.
## Solution
* Add `tracing::subscriber::set_default` which sets the default
subscriber and returns a drop guard. This drop guard will reset the
dispatch on drop.
* Add `tracing_core::dispatcher::set_default` method which sets the
default dispatch and returns a drop guard.
* Update `tracing_core::dispatcher::with_default` method to use the new
`tracing_core::dispatcher::set_default` method.
* Add test to confirm expected behavior
Fixes: #383
Tokio is experimenting with Discord, and the Tokio discord server has
a Tracing channel. This PR adds Discord links to READMEs.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
When `tracing` is not in use, no default subscriber will be set, and
tracing instrumentation points can be skipped. Currently, the
instrumentation macros detect this by testing if the callsite's
`Interest` is `never`. However, this is significantly slower than how
the `log` crate detects that there is no logger: we must call a function
through a trait object, do a relaxed load, construct an `Interest` from
an integer, and then test on the value of the `Interest`. Furthermore,
we must construct the callsite _at all_ in order to do this. Meanwhile,
when no logger is set, `log` can skip log records with only a single
relaxed atomic load.
## Solution
This branch adds a new private-API method in `tracing_core::dispatcher`
that allows us to check if a dispatcher has ever been set. If this is
false, then `tracing` has not yet been initialized and the callsite can
be elided entirely. Representing this as an atomic bool lets us perform
a single relaxed load and branch, without having to mess around with
`Interest`s and callsite vtables and so on. In cases where `tracing`
will never be used, this will always be false.
This the event macro performance with no subscriber set on par with the
`log` crate's performance when no logger is set. Spans are a bit slower
because they must still construct a disabled span object, but the span
macros are somewhat faster in this case than they were previously.
## Benchmark results
Before:
After:
Note that when no subscriber is set, skipping an event previously
took an average of around 2 ns, and skipping a span took around
5 ns. Now, skipping an event takes around 850 ps (about the
same as skipping a `log` macro when there's no logger), while
skipping a span macro takes around 2 ns.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
* tracing, core: improve no-subscriber performance significantly
This branch adds a new private API to `tracing-core` for checking if a
subscriber has ever been set. If a subscriber has never been set, we can
elide almost all of the event macro, and more of the span macro than we
were previously able to. Unlike checking a cached interest, which must
synchronize with the callsite registry, checking if a subscriber has
been set may be a relaxed rather than acquire load.
The performance of the `event!` macro (and the related `trace!`,
`info!`, etc macros) when no subscriber has ever been set (i.e., tracing
is not being used) is now comparable with that of the `log` crate, at
approximately 600 picoseconds (on my MacBook). As per `criterion`:
```
no_subscriber/event time: [610.43 ps 621.06 ps 633.20 ps]
change: [-64.247% -62.295% -60.263%] (p = 0.00 < 0.05)
Performance has improved.
Found 4 outliers among 100 measurements (4.00%)
1 (1.00%) high mild
3 (3.00%) high severe
no_subscriber/log time: [689.22 ps 707.34 ps 728.25 ps]
change: [+27.149% +33.128% +40.141%] (p = 0.00 < 0.05)
Performance has regressed.
Found 4 outliers among 100 measurements (4.00%)
4 (4.00%) high mild
no_subscriber_field/event
time: [623.28 ps 635.73 ps 648.88 ps]
change: [-59.666% -58.074% -56.649%] (p = 0.00 < 0.05)
Performance has improved.
Found 2 outliers among 100 measurements (2.00%)
2 (2.00%) high mild
no_subscriber_field/log time: [621.73 ps 632.07 ps 643.30 ps]
change: [+1.6194% +4.3288% +7.1454%] (p = 0.00 < 0.05)
Performance has regressed.
Found 3 outliers among 100 measurements (3.00%)
2 (2.00%) high mild
1 (1.00%) high severe
```
The worse performance of the `log` crate without fields than with fields
is probably statistical noise that criterion failed to eliminate.
The span macros cannot achieve this level of performance currently, as
the callsite must still be constructed in order to emit `log` events
when that feature flag is enabled. Future work will involve tuning the
`span!` macro some more. However, performance is improved by this change.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
* optimize disabled spans when log support is off
* tracing: add benchmarks for getting the subscriber
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
chore: build and publish documentation for each branch.
This commit introduces support for:
- building and deploying documentation for the master branch
- building and deploying (preview) documentation for each pull request
and for each PR
- adds a link in `README.md` pointing to the generated documentation
for the master branch
- notes the per-PR documentation previews in `CONTRIBUTING.md`
Closes#210
* core: remove `local_inner_macros`
This is unnecessary as we no longer support Rust 1.26
* core: prepare to release 0.1.5
Added:
- `std::error::Error` as a new primitive `Value` type (#277)
- `Event::new` and `Event::new_child_of` to manually construct `Event`s (#281)
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Currently, errors are typically recorded using their `fmt::Display` or
`fmt::Debug` implementations. This doesn't give the subscriber much
control over how the error is recorded --- in particular, it cannot
decide whether to format the error using `Display` or `Debug`, and it
cannot access the error's `source` or downcast it to another error type.
The `std::error::Error` type is implemented by a majority of errors in
both the standard library and in most crates, so its use is fairly
widespread.
## Solution
This commit adds `dyn std::error::Error + 'static` as a new primitive
type. The `'static` bound is included so that the error can be downcast.
Closes: #222
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Now that `tracing-subscriber` supports `Layer`ing subscribers, there is
a compelling use-case for constructing events without immediately
dispatching them to the default subscriber. In particular, this can be
used by a layer that aggregates or rolls up events and forwards those
aggregates to the root subscriber.
## Solution
This branch adds `new` and `new_child_of` functions to `Event`.
Fixes: #90
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This branch makes some minor tweaks to the `tracing-core` RustDoc,
including fixing some broken links, and using `#[doc(inline)]` on some
of the more important re-exports so they're highlighted front and centre
in the docs.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
* core: support `no-std` + `alloc`
Motivation
Users have expressed interest in using `tracing` on no_std platforms
with `liballoc`.
Solution
This branch adds `no_std` support to `tracing-core` by adding a `std`
feature flag (on by default) which can be disabled to use `libcore` +
`liballoc` instead of `libstd`.
When the `std` feature is disabled, `tracing-core` will use
`spin::Mutex` rather than `std::sync::Mutex`, and the thread-local
scoped dispatcher will be disabled (since it necessitates a defined OS
threading model, which may not exist on `no_std` platforms).
Refs: #213
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This branch makes a few small README and Cargo.toml changes:
* Add Azure Pipelines build status badges to Cargo.tomls
* Change README build status badges to Azure Pipelines
* Add "maintenance: experimental" badges to unreleased crates
* Link to `tracing` docs and crates.io page in the root README,
rather than `tracing-core`.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
As mentioned in #189, having a `FromStr` implementation for `Level`
could be useful for various cases (the first one being level parsing for
`fmt` filters).
We will be able to use it in the filter parser once it is released, with
something like:
```rust
fn parse_level(from: &str) -> Option<LevelFilter> {
from.parse::<Level>()
.ok()
.map(LevelFilter::Level)
.or_else(|| match from {
// Handle special values that are not levels but make sense as filters
"0" | "off" => Some(LevelFilter::Off),
"" => Some(LevelFilter::Level(Level::ERROR)),
_ => None,
})
}
```
## Motivation
The `tracing-core::dispatcher` module is currently somewhat
under-documented, which has caused confusion for many users. There
should be a detailed description of how traces are dispatched, and the
different methods of setting a default subscriber. In addition, the
`tokio` feature flag that enables automatic dispatcher propagation is
undocumented, which has also caused issues (see #169).
## Solution
This branch adds new module-level docs to the `dispatcher` module,
including examples of how default subscribers are set. It also corrects
a factual error in the documentation for `with_default`.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
As discussed in [PR 149], we determined that the `Subscriber::drop_span`
method should be deprecated in favour of `try_close`. This commit
deprecates it.
[PR 149]: https://github.com/tokio-rs/tracing/pull/149#discussion_r300802298
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This commit adds implementations of `Into<Option<Id>>`,
`Into<Option<&'a Id>>`, and `Into<Option<&'static Metadata<'static>>>`.
These should make using `span::Current` with functions like
`Span::record_follows_from` in `tracing` more fluid.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
As discussed in #136, a proposed `Layer` trait for composing subscribers
required should probably _not_ be responsible for managing ref-counts
and determining span closures. Instead, the root subscriber should be
responsible for this, and `Layer`s should be able to opt into a callback
that's notified _when_ a span is closed.
Adding a callback that's called on closure to `Layer` requires modifying
the `Subscriber` trait to allow indicating when a span closes.
## Solution
This branch attempts to do this without a breaking change, by adding a
new `try_close` trait method to `Subscriber`. `try_close` is identical
to `drop_span` except that it returns a boolean value, set to `true` if
the span has closed.
The `try_close` default implementation simply calls
`self.drop_span(...)` and returns `false`, so that if subscribers don't
care about tracking ref counts, close notifications will never be
triggered.
The `drop_span` documentation now indicates that it is "soft deprecated"
similarly to `std::error::Error`'s `description` method. This encourages
subscribers to implement the new API, but isn't a breaking change.
Existing _callers_ of `drop_span` are still able to call it without
causing issues. A subsequent PR will mark `drop_span` as deprecated
in favour of `try_close`.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This branch prepares `tracing-core` to release v0.1.1, and makes a few
minor README and crates.io metadata improvements.
Changelog:
### Added
- `Subscriber::current_span` API to return the current span (#148).
- `span::Current` type, representing the `Subscriber`'s view of the current
span (#148).
### Fixed
- Typos and broken links in documentation (#123, #124, #128, #154)
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
In many cases, it is valuable to be able to get the ID and metadata of
the span that the subscriber considers to be "current". This makes
propagating the span across easier, which is vital in cases such as
`tower-buffer`.
## Solution
This branch adds a new type to `tracing-core::span` representing a
subscriber's view of the current span. This type can indicate that there
is no current span, that the subscriber does not track the current span,
or it can contain the current span's ID and metadata. A new method
`current_span` is added to the `Subscriber` trait that returns this
current span type. In order to avoid a breaking change,
`Subscriber::current_span` has a default implementation that returns a
value indicating that the current span is not tracked by the subscriber.
A new `Span::current` function is added to `tracing::Span` that uses the
`tracing-core` API to return a handle to the current span. This is the
primary way users are expected to interact with this feature.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This branch removes all remaining references to the
non-existent `tracing-nursery` repository that weren't
removed in #142 and #141.
Closes#125
* chore: remove nursery mentions from .github
* core: remove references to `tracing-nursery`
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
#122 updated all crates to use Rust 2018 syntax, but I neglected to add
`edition = "2018"` to the `Cargo.toml`s.
## Solution
This fixes that.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
