This updates all crates' MSRVs to 1.49 if they were not already greater
than that (`tracing-appender` is at 1.53). Rust 1.49+ is required to
update `parking_lot` to v0.12 (see #1878). Also, `futures-task` (which I
believe is only needed as a transitive dep) now needs 1.45+, so this
also fixes our CI build.
Because `tracing-opentelemetry` previously required 1.46.0, it had a
separate CI MSRV job. Since 1.49.0 is greater than 1.46.0, the separate
check for `tracing-opentelemetry` is no longer needed.
In the process, I removed deprecated uses of
`core::atomic::spin_loop_hint`, which is replaced with
`core::hint::spin_loop` in 1.49.
# 0.3.0 (Oct 22, 2021)
This is a breaking release of `tracing-subscriber`. The primary breaking
change in this release is the removal of the dependency on the [`chrono`
crate], due to [RUSTSEC-2020-0159]. To replace `chrono`, support is
added for formatting timestamps using the [`time` crate] instead.
In addition, this release includes a number of other breaking API
changes, such as adding (limited) support for `#![no_std]` targets,
removing previously deprecated APIs, and more.
### Breaking Changes
- Removed APIs deprecated in the v0.2.x release series.
- Renamed `Layer::new_span` to `Layer::on_new_span` ([#1674])
- Removed `Layer` impl for `Arc<L: Layer<S>>` and `Arc<dyn Layer<S> +
...>` ([#1649])
- Replaced the [`chrono` crate] with the [`time` crate] for timestamp
formatting, to resolve [RUSTSEC-2020-0159] ([#1646])
- Removed `json` and `env-filter` from default features. They must now
be enabled explictly ([#1647])
- Changed `FormatEvent::format_event` and `FormatFields::format_fields`
trait methods to take a `Writer` type, rather than a `&mut dyn
fmt::Write` trait object ([#1661])
- Changed the signature of the `MakeWriter` trait by adding a lifetime
parameter ([#781])
### Changed
- **layer**: Renamed `Layer::new_span` to `Layer::on_new_span` ([#1674])
- **fmt**: Changed `FormatEvent::format_event` and
`FormatFields::format_fields` trait methods to take a `Writer` type,
rather than a `&mut dyn fmt::Write` trait object ([#1661])
- **json**, **env-filter**: `json` and `env-filter` feature flags are no
longer enabled by default ([#1647])
### Removed
- Removed deprecated `CurrentSpan` type ([#1320])
- **registry**: Removed deprecated `SpanRef::parents` iterator, replaced
by `SpanRef::scope` in [#1431] ([#1648)])
- **layer**: Removed deprecated `Context::scope` iterator, replaced by
`Context::span_scope` and `Context::event_scope` in [#1431] and
[#1434] ([#1648)])
- **layer**: Removed `Layer` impl for `Arc<L: Layer<S>>` and `Arc<dyn
Layer<S> + ...>`. These interfere with per-layer filtering. ([#1649])
- **fmt**: Removed deprecated `LayerBuilder` type ([#1673])
- **fmt**: Removed `fmt::Layer::on_event` (renamed to
`fmt::Layer::fmt_event`) ([#1673])
- **fmt**, **chrono**: Removed the `chrono` feature flag and APIs for
using the [`chrono` crate] for timestamp formatting ([#1646])
### Added
- **fmt**, **time**: `LocalTime` and `UtcTime` types for formatting
timestamps using the [`time` crate] ([#1646])
- **fmt**: Added a lifetime parameter to the `MakeWriter` trait,
allowing it to return a borrowed writer. This enables implementations
of `MakeWriter` for types such as `Mutex<T: io::Write>` and
`std::fs::File`. ([#781])
- **env-filter**: Documentation improvements ([#1637])
- Support for some APIs on `#![no_std]` targets, by disabling the `std`
feature flag ([#1660])
Thanks to @Folyd and @nmathewson for contributing to this release!
[#1320]: https://github.com/tokio-rs/tracing/pull/1320
[#1673]: https://github.com/tokio-rs/tracing/pull/1673
[#1674]: https://github.com/tokio-rs/tracing/pull/1674
[#1646]: https://github.com/tokio-rs/tracing/pull/1646
[#1647]: https://github.com/tokio-rs/tracing/pull/1647
[#1648]: https://github.com/tokio-rs/tracing/pull/1648
[#1649]: https://github.com/tokio-rs/tracing/pull/1649
[#1660]: https://github.com/tokio-rs/tracing/pull/1660
[#1661]: https://github.com/tokio-rs/tracing/pull/1661
[#1431]: https://github.com/tokio-rs/tracing/pull/1431
[#1434]: https://github.com/tokio-rs/tracing/pull/1434
[#781]: https://github.com/tokio-rs/tracing/pull/781
[`chrono` crate]: https://crates.io/crates/chrono
[`time` crate]: https://crates.io/crates/time
[RUSTSEC-2020-0159]: https://rustsec.org/advisories/RUSTSEC-2020-0159.html
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Currently, the `FormatEvent` and `FormatFields` traits in
`tracing-subscriber` are passed a `&mut dyn fmt::Write` trait object to
write formatted representations of events and fields to. This is fine,
but it doesn't give us the ability to easily provide additional
configuration to the formatter, such as whether ANSI color codes are
supported.
Issue #1651 describes some approaches for adding a way to expose the
ANSI color code configuration to custom formatters. In particular, the
proposed solution involves wrapping the `fmt::Write` trait object in an
opaque struct, which can then implement additional methods for exposing
information like "are ANSI colors enabled" to the formatter. Since this
changes the signature of the `FormatEvent::format_event` and
`FormatFields::format_fields` methods, it's a breaking change.
Therefore, we need to make this change _now_ if we want to get the API
change in for `tracing-subscriber` 0.3.
## Solution
This branch adds a `Writer` struct that wraps the `&mut dyn fmt::Write`
trait object, and changes the various method signatures as appropriate.
It does **not** actually implement the change related to ANSI color
formatting. Once we change these methods' signatures to accept a
`Writer` struct, we can add as many methods to that struct as we like
without making additional breaking API changes. Therefore, this branch
_just_ makes the breaking change that's necessary to get in before v0.3
is released.
Propagating the ANSI color configuration can be implemented in a future
branch.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This branch fixes some minor RustDoc issues. In particular:
- The `broken_intra_doc_links` lint was renamed to
`rustdoc::broken_intra_doc_links`. This generates a warning, since the
old name was deprecated.
- `ignore` code blocks are specifically for _Rust_ code that should not
be compiled, not for other text blocks. We were using `ignore` on JSON
blocks, which generates a warning.
- A bunch of links in `tracing-subscriber`'s RustDocs were broken. This
fixes that.
I also changed the Netlify configuration to run with `-D warnings`, so that
we can surface RustDoc warnings in CI builds.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
I'm writing a tracing subscriber layer that captures tracing events to
display in an in-program UI in a somewhat structured manner; as such I
don't want to just use the fmt layer's format-to-a-single-string
approach, and instead capture (currently) the event metadata, fields,
timestamp, thread, and spantrace, to be displayed in a
filterable/searchable/interactable manner later.
Currently, the only way to capture a `SpanTrace` is via
`SpanTrace::capture`. This (rightfully) captures the `SpanTrace` of the
current execution. However, I'm currently inside `Subscribe::on_event`;
I have the span right here! Even if `Span::current` happens to be the
same during `on_event` as when the event was fired, it seems more
"proper" to create a `SpanTrace` from the span passed in to me, rather
than looking up `Span::current`.
## Solution
The actual code change is almost trivial: all that needs to happen is to
expose a `SpanTrace::new` that takes a `Span` in addition to the
existing `SpanTrace::current`.
## Motivation
Fixes#1429
## Solution
Implemented as described in #1429, and migrated all internal uses of the
deprecated methods. All tests passed both before and after the migration
(9ec8130).
- Add a new method `SpanRef::scope(&self)` that returns a leaf-to-root
`Iterator`, including the specified leaf
- Add a new method `Scope::from_root(self)` (where `Scope` is the type
returned by `SpanRef::scope` defined earlier) that returns a
root-to-leaf `Iterator` that ends at the current leaf (in other
words: it's essentially the same as
`Scope::collect::<Vec<_>>().into_iter().rev()`)
- Deprecate all existing iterators, since they can be replaced by the
new unified mechanism:
- `Span::parents` is equivalent to `Span::scope().skip(1)` (although
the `skip` is typically a bug)
- `Span::from_root` is equivalent to `Span::scope().skip(1).from_root()`
(although the `skip` is typically a bug)
- `Context::scope` is equivalent to
`Context::lookup_current().scope().from_root()` (although the
`lookup_current` is sometimes a bug, see also #1428)
This backports PR #991 to v0.1.x. This is primarily necessary for the MSRV
bump, since some dependencies no longer compile on Rust 1.40.0.
This has already been approved on `master`, in PR #991, so it should be
fine to ship.
## Motivation
This will avoid breaking CI on new releases of clippy. It also makes the
code a little easier to read.
## Solution
- Convert `match val { pat => true, _ => false }` to `matches!(val, pat)`
- Remove unnecessary closures
- Convert `self: &mut Self` to `&mut self`
This bumps the MSRV to 1.42.0 for `matches!`.
The latest version of rust is 1.46.0, so as per
https://github.com/tokio-rs/tracing#supported-rust-versions this is not
considered a breaking change.
I didn't fix the following warning because the fix was not trivial/needed
a decision:
```
warning: you are deriving `Ord` but have implemented `PartialOrd` explicitly
--> tracing-subscriber/src/filter/env/field.rs:16:32
|
16 | #[derive(Debug, Eq, PartialEq, Ord)]
| ^^^
|
= note: `#[warn(clippy::derive_ord_xor_partial_ord)]` on by default
note: `PartialOrd` implemented here
--> tracing-subscriber/src/filter/env/field.rs:98:1
|
98 | / impl PartialOrd for Match {
99 | | fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
100 | | // Ordering for `Match` directives is based first on _whether_ a value
101 | | // is matched or not. This is semantically meaningful --- we would
... |
121 | | }
122 | | }
| |_^
= help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#derive_ord_xor_partial_ord
```
As a side note, this found a bug in clippy 😆https://github.com/rust-lang/rust-clippy/issues/6089
## Motivation
In order to get a compiler warning (or error) when links are broken.
Closes#940
## Solution
- [x] add `deny(broken_intra_doc_links)`
- [x] add a note to the CONTRIBUTING.md documentation on building docs locally
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
Co-authored-by: Joshua Nelson <joshua@yottadb.com>
This changes the logo to a wordmark. This should be consistent
with the ones for all the other Tokio crates, when we add them
elsewhere.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
PR #934 fixed a bug in the CI configuration where MSRV checks were not
being run correctly. After this was fixed, it was necessary to bump the
MSRV to 1.40.0, as the tests were no longer actually passing on 1.39,
because some dependencies no longer support it.
While updating the documentation to indicate that the new MSRV is 1.40,
I noticed that the note on the MSRV was located inconsistently in the
READMEs and `lib.rs` documentation of various crates, and missing
entirely in some cases. Additionally, there have been some questions on
what our MSRV _policies_ are, and whether MSRV bumps are considered
breaking changes (see e.g. #936).
## Solution
I've updated all the MSRV notes in the documentation and READMEs to
indicate that the MSRV is 1.40. I've also ensured that the MSRV note is
in the same place for every crate (at the end of the "Overview" section
in the docs), and that it's formatted consistently.
Furthermore, I added a new section to the READMEs and `lib.rs` docs
explaining the current MSRV policy in some detail. Hopefully, this
should answer questions like #936 in the future. The MSRV note in the
overview section includes a link to the section with further details.
Finally, while doing this, I noticed a couple of crates
(`tracing-journald` and `tracing-serde`) were missing top-level `lib.rs`
docs. Rather than just adding an MSRV note and nothing else, I went
ahead and fixed this using documentation from those crate's READMEs.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This puts the splash SVG in every crate's README, so
that it will be rendered on crates.io.
I also changed the link to an absolute URL, to ensure that
it works even outside of the repo.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
### Fixed
- **docs**: Incorrect formatting (#862)
### Changed
- **filter**: `LevelFilter` is now a re-export of the
`tracing_core::LevelFilter` type, it can now be used interchangably
with the versions in `tracing` and `tracing-core` (#853)
- **filter**: Significant performance improvements when comparing
`LevelFilter`s and `Level`s (#853)
- Updated the minimum `tracing-core` dependency to 0.1.12 (#853)
### Added
- **filter**: `LevelFilter` and `EnvFilter` now participate in
`tracing-core`'s max level hinting, improving performance
significantly in some use cases where levels are disabled globally
(#853)
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
### Fixed
- **fmt**: Fixed compilation failure on MSRV when the `chrono` feature
is disabled (#844)
### Added
- **fmt**: Span lookup methods defined by `layer::Context` are now also
provided by `FmtContext` (#834)
## Motivation
The MIT license states:
> The above copyright notice and this permission notice
> shall be included in all copies or substantial portions
> of the Software.
## Solution
Therefore the LICENSE files should be present in each crate directory,
so they are included with `cargo publish`.
Now that the new https://tokio.rs is live, we can add the new Tracing
logo to the RustDoc!
I also added a couple missing `html_root_url` attributes in published
crates.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
### Changed
- **parking_lot**: Updated the optional `parking_lot` dependency to
accept the latest `parking_lot` version (#774)
### Fixed
- **fmt**: Fixed events with explicitly overridden parent spans being
formatted as though they were children of the current span (#767)
### Added
- **fmt**: Added the option to print synthesized events when spans are
created, entered, exited, and closed, including span durations (#761)
- Documentation clarification and improvement (#762, #769)
Thanks to @rkuhn, @greenwoodcm, and @Ralith for contributing to this
release!
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Fixed
- **fmt**: Fixed an issue in the JSON formatter where using
`Span::record` would result in malformed spans (#709)
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
# 0.2.4 (April 6, 2020)
This release includes several API ergonomics improvements, including
shorthand constructors for many types, and an extension trait for
initializing subscribers using method-chaining style. Additionally,
several bugs in less commonly used `fmt` APIs were fixed.
### Added
- **fmt**: Shorthand free functions for constructing most types in `fmt`
(including `tracing_subscriber::fmt()` to return a
`SubscriberBuilder`, `tracing_subscriber::fmt::layer()` to return a
format `Layer`, etc) (#660)
- **registry**: Shorthand free function `tracing_subscriber::registry()`
to construct a new registry (#660)
- Added `SubscriberInitExt` extension trait for more ergonomic
subscriber initialization (#660)
### Changed
- **fmt**: Moved `LayerBuilder` methods to `Layer` (#655)
### Deprecated
- **fmt**: `LayerBuilder`, as `Layer` now implements all builder methods
(#655)
### Fixed
- **fmt**: Fixed `Compact` formatter not omitting levels with
`with_level(false)` (#657)
- **fmt**: Fixed `fmt::Layer` duplicating the fields for a new span if
another layer has already formatted its fields (#634)
- **fmt**: Added missing space when using `record` to add new fields to
a span that already has fields (#659)
- Updated outdated documentation (#647)
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
tracing-error's ErrorLayer depends upon subscriber changes that were
introduced in tracing "0.1.12" and depending on tracing = "0.1" allows
it to select versions that will not compile.
# 0.2.3 (March 5, 2020)
### Fixed
- **env-filter**: Regression where filter directives were selected in the order
they were listed, rather than most specific first (#624)
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
### Added
- **TracedError**: `TracedError`, an error type wrapper that annotates
an error with the current span.
- **SpanTrace**:`SpanTrace::status` method and `SpanTraceStatus` type
for determing whether a `SpanTrace` was successfully captured (#614)
### Changed
- **SpanTrace**: Made backtrace formatting more consistent with upstream
changes to `std::backtrace` (#584)
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
The current impl for `ExtractSpanTrace` is implemented for references and takes &self as its receiver type, which causes it to reborrow the error and the lifetime of the returned SpanTrace is tied to this new borrow. This prevents the SpanTrace from outliving the borrow created from the `span_trace` call which functionally means you cannot return references to the borrowed `SpanTrace`s
## Solution
This changes the receiver type from `&dyn Error` to `dyn Error` so that the `&` in the `&self` pattern ends up matching against the original borrow, which could be a borrow that was passed in from another function, which lets us use the longer lifetime as the lifetime for the reference to the SpanTrace.
## Motivation
Because `SpanTrace` does not have a header, implementations that wish to print a `SpanTrace` must print their own header before printing the `SpanTrace` itself. When the `SpanTrace` is empty this ends up inserting a header with no content after it, and the only way to avoid this via the current API is to `to_string` the `SpanTrace` prior to printing the header to check if `SpanTrace` would print any content.
## Solution
This change adds a `SpanTrace::status()` fn and accompanying `SpanTraceStatus` enum type to indicate to the user what will be printed if anything when the user attempts to display/debug print the `SpanTrace`.
## Motivation
The tracing_error crate should provide some basic functionality for
instrumenting Errors with `SpanTraces` generically. The goal is to make
it easy for users to instrument their errors without needing to add a
`SpanTrace` to every error they construct.
## Solution
Critically this trait provides 3 traits for instrumenting errors,
`InstrumentResult`, `InstrumentError`, and `ExtractSpanTrace`. The first
two traits expose a `in_current_span()` method that can work on a
`Result<T, E: InstrumentError>` and an `Error`, respectively, that wraps
the error type in a `TracedError` that stores the inner error and a
SpanTrace. The third trait, `ExtractSpanTrace`, is used to retrieve the
span_trace member of a `TracedError` from a `&dyn Error` trait object.
This is done by downcasting the error to a `TracedError` and returning
the inner `span_trace` if it is successful. By default this only works
because the inner error is stored in a Box as a trait object, which
prevents it from being part of the type signature for `TracedError`.
However, this crate also exposes a second version of `TracedError` that
does not box the inner error, thus avoiding the need for heap
allocation, which it accomplishes by type erasing the `TracedError<E>`
into a `TracedError<()>` while iterating through the error `source()`
chain.
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>
### Changed
- **filter**: `EnvFilter` directive selection now behaves correctly
(i.e. like `env_logger`) (#583)
### Fixed
- **filter**: Fixed `EnvFilter` incorrectly allowing less-specific
filter directives to enable events that are disabled by more-specific
filters (#583)
- **filter**: Multiple significant `EnvFilter` performance
improvements, especially when filtering events generated by `log`
records (#578, #583)
- **filter**: Replaced `BTreeMap` with `Vec` in `DirectiveSet`,
improving iteration performance significantly with typical numbers of
filter directives (#580)
A big thank-you to @samschlegel for lots of help with `EnvFilter`
performance tuning in this release!
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This PR changes the SpanTrace display format so that it no longer outputs a header prior to the output of the spans, and it changes the debug format to add one without newlines and support pretty formatting when formatting with `{:#?}`. These changes match recent changes made to the format of std::backtrace::Backtrace.
## Motivation
Intra-workspace dependencies can go out of sync if only referencing
crates.io, where changing one crate locally and testing the whole
library will result in errors stemming from two different versions of
the same trait etc. This is hard to keep track of and makes development
more difficult than it needs to be.
## Solution
Afaik it's common practice to specify both a version and a path as per
[the cargo docs][1]. This is what tokio does with its subcrates too.
[1]: https://github.com/rust-lang/cargo/blob/master/src/doc/src/reference/specifying-dependencies.md#multiple-locations.
# 0.2.0 (February 4, 2020)
### Breaking Changes
- **fmt**: Renamed `Context` to `FmtContext` (#420, #425)
- **fmt**: Renamed `Builder` to `SubscriberBuilder` (#420)
- **filter**: Removed `Filter`. Use `EnvFilter` instead (#434)
### Added
- **registry**: `Registry`, a `Subscriber` implementation that `Layer`s
can use as a high-performance, in-memory span store. (#420, #425,
#432, #433, #435)
- **registry**: Added `LookupSpan` trait, implemented by `Subscriber`s
to expose stored span data to `Layer`s (#420)
- **fmt**: Added `fmt::Layer`, to allow composing log formatting with
other `Layer`s
- **fmt**: Added support for JSON field and event formatting (#377,
#415)
- **filter**: Documentation for filtering directives (#554)
### Changed
- **fmt**: Renamed `Context` to `FmtContext` (#420, #425) (BREAKING)
- **fmt**: Renamed `Builder` to `SubscriberBuilder` (#420) (BREAKING)
- **fmt**: Reimplemented `fmt::Subscriber` in terms of the `Registry`
and `Layer`s (#420)
### Removed
- **filter**: Removed `Filter`. Use `EnvFilter` instead (#434)
(BREAKING)
### Fixed
- **fmt**: Fixed memory leaks in the slab used to store per-span data
(3c35048)
- **fmt**: `fmt::SubscriberBuilder::init` not setting up `log`
compatibility (#489)
- **fmt**: Spans closed by a child span closing not also closing
_their_ parents (#514)
- **Layer**: Fixed `Layered` subscribers failing to downcast to their
own type (#549)
- **Layer**: Fixed `Layer::downcast_ref` returning invalid references
(#454)
Fixes#515Fixes#458
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This updates `tracing-error` to depend on `tracing-subscriber` from
crates.io, rather than via a path dependency. This means that git deps
on `tracing-error` should "actually work" now.
Additionally, I've updated the `tracing-subscriber` dep to only enable
the feature flags `tracing-error` requires. This means that depending on
`tracing-error` won't enable `tracing-subscriber`'s default features
unless they are actually needed.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
A lot of folks have expressed interest in being able to capture the
current `tracing` span context when an error type is _constructed_, so
it can eventually be displayed when the error is handled. Since span
entry is stackful, the error may not be formatted or otherwise handled
within a span context that is in any way related to the one where the
error occurred — and this is only made worse when "channels" are
involved.
## Solution
This branch introduces a new crate, `tracing-error`, which will contain
integrations and types for enriching errors with `tracing` span contexts.
Currently, this crate contains the following:
- A `SpanTrace` type, which captures the current span and allows it to be
inspected later.
- A `Layer` implementation which may be added to a `Subscriber` to
enable capturing traces for errors. This layer will format fields and
insert them into span extensions, **if no other layer has already
added such an extension** using the same formatter. This reuses the
formatting traits from `tracing-subscriber`'s `fmt` module.
## Notes
Note that we have not actually added any new error types or error
wrapper types. I would like to provide these in the future, so that
span capturing can be seamlessly integrated into the rest of the Rust
error handling ecosystem. However, this will take some additional
experimentation. For now, we want to release the `SpanTrace` type so
that other libraries and applications may use _it_ as an integration point.
We'll need to add more documentation and examples for these APIs, and
can do that in follow-up branches.
Closes#464
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Co-authored-by: Jane Lusby <jlusby@yaah.dev>
* docs: add third-party crates to docs
This branch adds a list of related crates not in this repository to the
`tracing` RustDoc, the `tracing` README, and the root repository README.
(cc @jonhoo, @jtescher, @pkinsky, @GregBowyer, @zanria, @hlb8122)
Closes#373
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
