Most of these changes are places where lifetimes were named, but can be
elided. Then a few cases where a lifetime was elided, but actually
resolves to a named lifetime. So lots of lifetimes.
With the release of Rust 1.74, there are some new or modified clippy
lints that need adaption in the code.
The main change was the removal of the `private_in_public`.
https://rust-lang.github.io/rfcs/2145-type-privacy.html
Then two more changes were required, in one case to adhere a lint and
the other to allow it. When talking about what an "application" needs to
do when setting up `tracing-error`, it makes sense to include `fn
main()` in the doctest, even though the lint recommends against it.
As part of upgrading syn to 2.0 (e.g.,
https://github.com/tokio-rs/tracing/pull/2516), we need to bump the MSRV
to 1.56. As part of this PR, I've:
- Updated the text descriptions of what would be an in-policy MSRV bump
to use more recent versions of rustc. The _niceness_ of said version
numbers are purely coincidental.
- I've removed some of the exceptions made in CI.yml in order to support
some crates with a higher MSRV.
There are new warnings as errors reported by clippy in Rust 1.67.0.
This are causing builds to fail, e.g.:
https://github.com/tokio-rs/tracing/actions/runs/4027112923/jobs/6922513360
In both cases they are reports of lifetimes that can be elided. This
change removes the unnecessary lifetime annotations to make clippy
happy.
This branch adds documentation and tests noting that the `#[instrument]`
macro accepts `tracing::Level` directly. Using `tracing::Level` directly
allows for IDE autocomplete and earlier detection of typos.
The documentation for tracing-attributes was also rewritten to remove
the usage of the second-person perspective, making it more consistent
with the rest of tracing's documentation.
Co-authored-by: David Barsky <me@davidbarsky.com>
## Motivation
The Rust 1.60 release introduced a few new lints that trigger on the
`tracing` codebase. In particular, `clippy` added some new lints for
method naming, and the `unreachable_pub` lint now seems to be triggered
incorrectly by `pub use foo as _` re-exports.
## Solution
This branch fixes the lints.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
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.
## 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>
## 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`.
Forward-port of #1431 and #1434
* subscriber: unify span traversal (#1431)
## Motivation
Fixes#1429 (forwardport from v0.1.x branch)
## 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)
* subscriber: add Context method for resolving an Event's SpanRef (#1434)
## Motivation
Fixes#1428 (forward-port from v0.1.x)
## Solution
Adds a new `Context::event_span` method as proposed in the issue.
No existing formatters were changed to use it yet, that seems like a
secondary issue (especially if they already work correctly).
## Motivation
Resolves#1073, quoting from there:
> If we changed this to `Option<NonNull<()>>` we could benefit from
> niche optimization, saving us the option discriminant and making
> this return a single word pointer. That may in turn let us benefit
> from additional optimizations. This could make downcasting slightly
> faster.
## Solution
I've made the change to the function signature and let rustc guide me
through the process of fixing all callers. This was mostly
straightforward but it is `unsafe` code so I'm not sure the changes here
are correct.
## Motivation
Currently, the `tracing-subscriber` crate has the `MakeWriter` trait for
customizing the io writer used by `fmt`. This trait is necessary (rather
than simply using a `Write` instance) because the default implementation
performs the IO on the thread where an event was recorded, meaning that
a separate writer needs to be acquired by each thread (either by calling
a function like `io::stdout`, by locking a shared `Write` instance,
etc).
Right now there is a blanket impl for `Fn() -> T where T: Write`. This
works fine with functions like `io::stdout`. However, the _other_ common
case for this trait is locking a shared writer.
Therefore, it makes sense to see an implementation like this:
``` rust
impl<'a, W: io::Write> MakeWriter for Mutex<W>
where
W: io::Write,
{
type Writer = MutexWriter<'a, W>;
fn make_writer(&self) -> Self::Writer {
MutexWriter(self.lock().unwrap())
}
}
pub struct MutexWriter<'a, W>(MutexGuard<'a, W>);
impl<W: io::Write> io::Write for MutexWriter<'_, W> {
// write to the shared writer in the `MutexGuard`...
}
```
Unfortunately, it's impossible to write this. Since `MakeWriter` always
takes an `&self` parameter and returns `Self::Writer`, the generic
parameter is unbounded:
```
Checking tracing-subscriber v0.2.4 (/home/eliza/code/tracing/tracing-subscriber)
error[E0207]: the lifetime parameter `'a` is not constrained by the impl trait, self type, or predicates
--> tracing-subscriber/src/fmt/writer.rs:61:6
|
61 | impl<'a, W: io::Write> MakeWriter for Mutex<W>
| ^^ unconstrained lifetime parameter
error: aborting due to previous error
```
This essentially precludes any `MakeWriter` impl where the writer is
borrowed from the type implementing `MakeWriter`. This is a significant
blow to the usefulness of the trait. For example, it prevented the use
of `MakeWriter` in `tracing-flame` as suggested in
https://github.com/tokio-rs/tracing/pull/631#discussion_r391138233.
## Proposal
This PR changes `MakeWriter` to be generic over a lifetime `'a`:
```rust
pub trait MakeWriter<'a> {
type Writer: io::Write;
fn make_writer(&'a self) -> Self::Writer;
}
```
The `self` parameter is now borrowed for the `&'a` lifetime, so it is
okay to return a writer borrowed from `self`, such as in the `Mutex`
case.
I've also added an impl of `MakeWriter` for `Mutex<T> where T: Writer`.
Unfortunately, this is a breaking change and will need to wait until we
release `tracing-subscriber` 0.3.
Fixes#675.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Right now TracedError is pretty much incompatible with enum heavy error
handling implementations. The way its currently designed you'd have to make
sure that each leaf error independently is wrapped in a `TracedError` so that
all sources end up capturing a SpanTrace.
## Solution
To resolve this I've added a `map` method for transforming the inner type of a
TracedError while preserving the existing SpanTrace. This is still a bit
cumbersome, where before you'd be able to write `result.map_err(|source|
MyError { source, some_context })` now you'll have to write
`result.map_err(|source| source.map(|source| MyError { source, some_context
}))`. To fix this we should probably eventually add an extension trait on
`Result` but I want to experiment with that half of the change in `zebra`
before committing to an API, since it can easily be done out of tree.
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
#940
## Solution
This changes the docs.rs links, many of which were broken (or would have
been broken on the next release). It also converts some links I missed
the first time (maybe they were added after I opened the PR?).
This PR renames the following:
- `tracing_core::Subscriber` to `tracing_core::Collect`
- `tracing_subscriber::layer::Layer` to `tracing_subscriber::layer::Subscribe`
Authored-by: David Barsksy <dbarsky@amazon.com>
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
## 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
This branch updates all crate versions to 0.2.x. After this PR merges,
we can now develop `tracing`/`tracing-core` v0.2.x on `master`.
There is now a separate, protected `v0.1.x` branch. Changes backported
to 0.1 versions of `tracing` crates can be merged to that branch.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## 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>
