## Motivation
Clippy [now warns us][1] that comparing trait object pointers with
`ptr::eq` is bad, because vtable addresses are not guaranteed to be
unique due to the compiler merging vtables, and vtables for the same
trait impl may have different addresses in different compilation units.
In practice, I don't believe this actually effects `tracing-core`'s use
case for this comparison. Because callsites must be static, the data
component of the trait object wide pointer will always be unique, even
if the compiler merges the vtables for all the identical generated
`Callsite` impls (which it may very well do!).
## Solution
Although this is probably not an issue in practice, I still thought it
was good to fix the clippy warning, and to be more explicit that it's
the data pointer comparison that's load-bearing here. I've updated the
`PartialEq` impl for `callsite::Identifier` to cast to `*const ()` to
extract the data address from the wide pointer.
[1]: https://rust-lang.github.io/rust-clippy/master/index.html#vtable_address_comparisons
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
There are unnecessary spaces. Also, there is a point that requires space.
* chore: Remove duplicated spaces
* chore: Add space to make code consistent
## Motivation
Currently, the only way to interact with `Value`s is to record them with
a visitor. In the most common case, where typed data is not needed,
`Value`s are recorded with their `fmt::Debug` implementations — a
visitor which does not implement the `record_${TYPE}` traits will
automatically fall back to recording all primitive value types with
`Debug`. However, implementing a visitor requires a bit of boilerplate:
an entire trait implementation has to be written, and a visitor object
passed to `record`.
## Solution
This branch hopes to simplify this common case by adding a `Debug`
implementation to _all_ `dyn Value` trait objects. This is equivalent
to a visitor that only implements `record_debug`, but requiring less
boilerplate.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Currently, `tracing` uses GitHub Actions for CI. However, we have
previously used both Travis and Azure Pipelines CI. Some artifacts of
previous CI configurations, such as badges and config files, still exist
in the repo. This can be confusing, since some of these CI
configurations imply things that aren't currently true (such as old MSRV
versions).
## Solution
This branch removes the following:
- Azure Pipelines badges from cargo metadata. These currently show up
as "never built" on crates.io, since the Azure build is turned off. So, we
should just remove them.
- `.travis.yml`. We don't use Travis and there's no sense keeping around
an old config file.
- `azure-pipelines.yml`. Similarly, we no longer need this.
Fixes: #669
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
### Added
- `field::Empty` type for declaring empty fields whose values will be
recorded later (#548)
- `field::Value` implementations for `Wrapping` and `NonZero*` numbers
(#538)
### Fixed
- Broken and unresolvable links in RustDoc (#595)
Thanks to @oli-cosmian for contributing to this release!
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This commit fixes several RustDoc links which were either broken
(without references) or had unresolvable references.
It looks like nightly RustDoc has recently gotten much smarter about
finding links that were unresolvable. These had always been broken, but
they used to silently 404. Now, the nightly build of RustDoc will emit a
warning, which we deny, causing the build to fail. This should fix CI
(as well as actually fixing the wrong links).
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Right now, there is no way to indicate that a span field _currently_
has no value but that a value will be recorded later. Tracing used to
support this concept, but when we added local-variable shorthand, it was
removed from the macros, as we needed to use the previous syntax for
indicating empty fields for local variable shorthand. See #77 for
details.
This commit side-steps the problem of determining an appropriate
_syntax_ for empty fields by adding a special value _type_, called
`Empty`. Now, empty values can be indicated like
```rust
span!("my_span", foo = 5, bar = tracing::field::Empty);
```
The `Empty` type implements `Value`, but its' `record` method is a no-op
that doesn't' call any functions on the visitor. Therefore, when a field
is empty, the visitor will not see it. An empty field can then be
recorded later using `Subscriber::record` (or the corresponding `Span`
method in `tracing`).
Closes#77
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
For tracing there's no difference between a `NonZero*` or `Wrapping`
type and their underlying type. This allows such types to directly be
referenced by the tracing macros without requiring additional method
calls or boilerplate.
## Solution
Implemented `Value` for `Wrapping<T: Value>` and for all the `NonZero*`
types from `std::num`.
This required a slight refactoring of the macros generating the regular
integer impls as to reduce the amount of generated code.
# 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>
