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.
This is the `v0.1.x` branch sister PR to #3164 (for the `master`
branch), since `clippy --fix` on another branch is a much better way to
apply these changes than backporting.
The commit 1cb523b87d3d removed this cfg gate on master. However, when
the change was backported in 1cb523b87d3d the docs were updated but the
cfg change was omitted.
This made the docs misleading, since they say "This method itself is
still available without the feature flag."
There are 2 triggers which will cause a subscriber to receive a call to
`Subscriber::register_callsite` for a specific callsite.
1. The first time the event or span at that callsite is executed.
2. When a new subscriber is added or removed (for example, calls to
`set_default` or `with_default`)
It is trigger (2) that will cause a new subscriber to receive
`Subscriber::register_callsite` for all the callsites which had already
been registered before it became active.
When a callsite is registered for trigger (1), the callsite starts in
state `UNREGISTERED`.
The first thread to encounter the callsite will transition it to
`REGISTERING` and determine the overall interest for the callsite by
registering with all known dispatchers (which will call into
`Subscriber::register_callsite`).
Once that is complete, the callsite is added to the list of all known
callsites and its state is transitioned to `REGISTERED`.
is (re)built for all known dispatchers. The callsite starts in state
`UNREGISTERED`. The This calls down into
`Subscriber::register_callsite` for each subscriber. Once that is
complete, the callsite is added to the global list of known callsites.
While the callsite interest is being rebuilt, other threads that
encounter the callsite will be given `Interest::sometimes()` until the
registration is complete. However, if a new subscriber is added during
this window, all the interest for all callsites will be rebuilt, but
because the new callsite (in state `REGISTERING`) won't be included
because it isn't yet in the global list of callsites.
This can cause a case where that new subscriber being added won't
receive `Subscriber::register_callsite` before it receives the subsequent
call to `Subscriber::event` or `Subscriber::new_span`.
The documentation on [Registering Callsites] is not very explicit on
this point, but it does suggest that `Subscriber::register_callsite`
will be called before the call to either `Subscriber::event` or
`Subscriber::new_span`, and the current behavior can break this implicit
contract.
[Registering Callsites]: https://docs.rs/tracing-core/0.1.32/tracing_core/callsite/index.html#registering-callsites
This change swaps the order of rebuilding the callsite interest and
adding the callsite to the global list so that the callsite gets pushed
first, avoiding this window in which a subscriber won't get a call to
`register_callsite`.
As such, a callsite may have its interest read before it is set. In this
case, the existing implementation will return `Interest::sometimes()`
for the `DefaultCallsite` implementation. Other implementations (outside
of the `tracing` project) may perform this differently, but in this
case, there is no documented guarantee regarding the ordering.
A regression test is included which provokes the race condition 100% of
the time before the changes in this fix.
Fixes: #2743
Co-authored-by: David Barsky <me@davidbarsky.com>
This modifies the `tracing_subscriber::reload` layer to also set the
`log` crate's max level with the current max `tracing` level filter
after reloading. If reloading the subscriber caused the max `tracing`
level to change, this ensures that the change is propagated to the `log`
crate as well. In the case where the max level was made more verbose,
this will ensure that `log` records which were previously disabled are
enabled correctly; in the case where it was made less verbose, this
improve performance by not having to perfrom more costly filtering for
those `log` records.
The `log` max level is set only after rebuilding the callsite interest
cache, which is what sets the max `tracing` level filter. This ensures
that we pass the latest state to the `log` crate.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Expose the index of the field in order to support cases such as sending field information
by index instead of by the string name in Tokio Console. Details:
https://github.com/tokio-rs/console/issues/462#issuecomment-1830842319
## Solution
Adds a new API which exposes the index of a field, which is how it is stored internally
(together with a reference to the `FieldSet` containing the ordered field names.
Signed-off-by: hi-rustin <rustin.liu@gmail.com>
Co-authored-by: Hayden Stainsby <hds@caffeineconcepts.com>
## Motivation
I've created a library for better customization of JSON log lines and would like to make it more discoverable.
This subscriber could help with a lot of issues such as #1531
## Solution
Add `json-subscriber` to the ecosystem.
Clippy in 1.80.0 alerted us to the fact that `SerializeField` was never
constructed (and due to its non-`pub` member, it can't be constructed
outside the `tracing-serde` crate where it's from).
This change fixes the definition to hold a reference to a `Field`, which
is what the other `Serialize*` types do. It also implements `AsSerde`
for this type and uses it inside the `SerializeFieldSet` type.
As a bonus, Clippy is now also happy that the type is constructed.
The example collector in the `tracing-serde` crate was also renamed from
`JsonSubscriber` to `JsonCollector`.
Some additional doc formatting issues in `tracing-subscriber` were fixed
so that list items that run to multiple lines are correctly indented.
Currently, a keyword like `type` fails compilation as (a path segment of) a field name, for no clear reason. Trying to use `r#type` instead leads to the `r#` being part of the field name, which is unhelpful¹.
Don't require the field path to match a `macro_rules!` `expr`, use repeated `tt` instead. I can't tell why this was ever required: The internal stringify macro was introduced in 55091c92ed (diff-315c02cd05738da173861537577d159833f70f79cfda8cd7cf1a0d7a28ace31b) with an `expr` matcher without any explanation, and no tests are failing from making it match upstream's `stringify!` input format.
Special thanks to whoever implemented the unstable `macro-backtrace` feature in rustc, otherwise this would have been nigh impossible to track down!
¹ this can likely be fixed too by some sort of "unraw" macro that turns `r#foo` into `foo`, but that's a separate change not made in this PR
In the documentation of the layer context span_scope method, the note
contained a reference to a `scope()` method, which was removed some time
ago. Also fixed a phrasing error above.
Fixes: #2890
Users may want to pass data to `Subscribe`s which is not valid UTF-8. Currently, it would have to be encoded into `&str` to be passed as a field value.
This branch adds a `record_bytes` method to `Visit`. It has an implementation falling back to `record_debug` so it is not be a breaking change.
`JsonVisitor` got an overridden implementation as it should not use `Debug` output and encode it as a string, but rather store the bytes as an array.
`PrettyVisitor` go an overridden implementation to make the output more pretty.
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Const argumetns in `level!` macros do not work when in the first
position.
This also seems to have fixed#2748 where literals for fields names like
`info!("foo" = 2)` could not be used outside the `event!` macro.
Fixes#2837Fixes#2738
## Solution
Previsously, `level!($(args:tt))` was forwarded to `event!(target: ...,
level: ..., { $(args:tt) })` but the added curly braces seem to have
prevented the `event` macro from correctly understanding the arguments
and it tried to pass them to `format!`.
With this change there may have some performance impact when expanding
the macros in most cases where the braces could have been added as it
will take one more step.
These are the two relevant `event!` blocks I believe, the new tests used
to expand to the first one (with empty fields), now they expand to the
latter:
```
(target: $target:expr, $lvl:expr, { $($fields:tt)* }, $($arg:tt)+ ) => (
$crate::event!(
target: $target,
$lvl,
{ message = $crate::__macro_support::format_args!($($arg)+), $($fields)* }
)
);
(target: $target:expr, $lvl:expr, $($arg:tt)+ ) => (
$crate::event!(target: $target, $lvl, { $($arg)+ })
);
```
If something like `warn!(?foo)` and `warn!(name: "foo", ?foo)` works, then `warn!(name: "foo", target: "foo_events", ?foo)` should arguably also work. Before this change the more complicated variants of the macros however required a message argument, due to the usage of the `+` specifier in the macro definitions. This commit changes the `+` (1 or more) to `*` (0 or more), which matches how the `field` tokens are used in the simpler variants of the macro.
## Motivation
In the simple macro cases with e.g. only "name" or only "target" these
prefixes exist, but for the more complicated cases like "name + target"
the prefixes were not piped through and silently ignored. This led to
the compiler complaining about `Value` not being implemented despite the
usage of the `?` or `%` prefixes:
<img width="1056" alt="Bildschirmfoto 2024-02-14 um 12 38 00"
src="https://github.com/tokio-rs/tracing/assets/141300/f8b0b1af-fe66-41d8-9a08-2ecba2d67f9e">
## Solution
This change adds the missing prefixes to the `$($k)` tokens, like they
already exist for the simple cases mentioned above.
This results in a substantial performance improvement,
and is compatible with our MSRV.
Signed-off-by: Alex Saveau <saveau.alexandre@gmail.com>
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
This allows to manually map tracing levels to journald levels.
It seems that @little-dude, who started the original PR, doesn't have
time to finish this, so I picked it up. Reapplied the changes to the
newest master branch and fixed the latest comments/issues.
This will also fix/close:
Closes#2649Closes#2661Closes#2347 (the original pr)
fixes https://github.com/tokio-rs/tracing/actions/runs/6785393202/job/18443641813
cargo test runs tests in the same file in parallel by default, causing race condition,
this can be proven by running
`cargo test --test reload -- --test-threads=1` => successes
`cargo test --test reload -- --test-threads=2` => flaky
multiple times
This fix runs only the two tests in serial.
We could seperate the tests in different files, but they share the same testing dependencies, so I left them in the same file.
There has been interest around publishing tracing-mock to crates.io
for some time. In order to make this possible, documentation and some
code clean up is needed.
The `expect` module, which contains constructor functions for many of
the other `tracing-mock` modules needs documentation and examples.
This change adds documentation to the `expect` module and all the public
APIs within it. This includes doctests on all the methods which serve as
examples.
The lint for `missing_docs` has been enabled for the entire
`tracing-mock` crate! This has been done together with all the
other lints that are enabled on the other crates in this project.
The `event::msg("message")` constructor was removed, in favor of
requiring an explicit construction via
`expect::event().with_fields(expect::msg("message"))`. This is
appropriate to reduce the API surface that would need to be supported in
the future and also because the `event::msg` constructor could be
overridden by a subsequent usage of `with_fields`. The shorthand
`expect::message()` was renamed to `expect::msg` to make this
change less burdensome.
The `span::named("name")` constructor was removed, in favor of requiring
an explicit construction via `expect::span.with_name("name")`. The
latter isn't much longer and since #3097, a string with the name can
be passed directly everywhere that an `ExpectedSpan` is required.
This change also sets the `missing_docs` lint to warn for the entire
`tracing-mock` crate, making it ready to publish (once backported).
Refs: #539
The `with_ancestry` methods on `NewSpan` and `ExpectedEvent` provide a
way to match whether the span or event is a contextual or explicit root
or if it has a contextual or explicit parent span.
However, in the case of matching on a contextual or explicit parent
span, only the span name could be used for matching. This is
sufficiently precise when testing tracing instrumentation in other
libraries or applications as opposed to testing tracing itself.
It is likely that a user would like to test that some span or event has
a specific span as a parent, and not just any span with a specific name,
in many cases, all the possible parent spans may have the same name.
This is the case when testing tracing instrumentation in Tokio.
To solve this problem, the `Ancestry` struct was renamed to
`ExpectedAncestry` and in the case of expecting an explicit or
conextual parent, an `ExpectedSpan` object can be passed in. This
provides the maximum possible flexibility.
The convenience functions in the `expect` module now take
`Into<ExpectedSpan>` so that existing tests that pass a string type
object for the parent will see the same behaviour as previously and
shorthand use for expected Ids is also available.
Additionally, the span checking code has been unified between the
`MockCollector` and `MockSubscriber` cases and the assertion
descriptions have been improved to make them more readable.
Many of the methods on `MockCollector` take an `ExpectedSpan`. This
often requires significant boilerplate. For example, to expect that a
span with a specific name enters and then exits, the following code is
needed:
```rust
let span = expect::span().named("span name");
let (collector, handle) = collector::mock()
.enter(span.clone())
.exit(span)
.run_with_handle();
```
In order to make using `tracing-mock` more ergonomic and also more
compact, the `MockCollector` and `MockSubscriber` methods that previous
took an `ExpectedSpan`, are now generic over `Into<ExpectedSpan>`.
There are currently 3 implementations of `From` for `ExpectedSpan` which
allow the following shorthand uses:
`T: Into<String>` - an `ExpectedSpan` will be created that expects to
have a name specified by `T`.
```rust
let (collector, handle) = collector::mock()
.enter("span name")
.exit("span name")
.run_with_handle();
```
`&ExpectedId` - an `ExpectedSpan` will be created that expects to have
the expected Id. A reference is taken and cloned internally because the
caller always needs to use an `ExpectedId` in at least 2 calls to the
mock collector/subscriber.
```rust
let id = expect::id();
let (collector, handle) = collector::mock()
.new_span(&id)
.enter(&id)
.run_with_handle();
```
`&ExpectedSpan` - The expected span is taken by reference and cloned.
```rust
let span = expect::span().named("span name");
let (collector, handle) = collector::mock()
.enter(&span)
.exit(&span)
.run_with_handle();
```
In Rust, taking a reference to an object and immediately cloning it is
an anti-pattern. It is considered better to force the user to clone
outside the API to make the cloning explict.
However, in the case of a testing framework, it seems reasonable to
prefer a more concise API, rather than having it more explicit.
To reduce the size of this PR and to avoid unnecessary churn in other
crates, the tests within the tracing repo which use `tracing-mock` will
not be updated to use the new `Into<ExpectedSpan>` capabilities. The new
API is backwards compatible and those tests can remain as they are.
When recording the parent of an event or span, the `MockCollector`
treats an explicit parent of `None` (i.e. an event or span that is an
explicit root) in the same way as if there is no explicit root. This
leads to it picking up the contextual parent or treating the event or
span as a contextual root.
This change refactors the recording of the parent to use `is_contextual`
to distinguish whether or not an explicit parent has been specified. The
actual parent is also written into an `Ancestry` enum so that the
expected and actual values can be compared in a more explicit way.
Additionally, the `Ancestry` struct has been moved into its own module and
the check behavior has been fixed. The error message has also been
unified across all cases.
Another problem with the previous API is that the two methods
`with_contextual_parent` and `with_explicit_parent` are actually
mutually exclusive, a span or event cannot be both of them. It is also a
(small) mental leap for the user to go from `with_*_parent(None)` to
understanding that this means that a span or event is a root (either
contextual or explicit).
As such, the API has been reworked into a single method `with_ancestry`,
which takes an enum with the following four variants:
* `HasExplicitParent(String)` (parent span name)
* `IsExplicitRoot`
* `HasContextualParent(String)` (parent span name)
* `IsContextualRoot`
To make the interface as useable as possible, helper functions have been
defined in the `expect` module which can be used to create the enum
variants. Specifically, these take `Into<String>` parameter for the span
name.
Given the number of different cases involved in checking ancestry,
separate integration tests have been added to `tracing-mock`
specifically for testing all the positive and negative cases when
asserting on the ancestry of events and spans.
There were two tests in `tracing-attributes` which specified both an
explicit and a contextual parent. This behavior was never intended to
work as all events and spans are either contextual or not. The tests
have been corrected to only expect one of the two.
Fixes: #2440
It currently isn't possible to differentiate spans with the same name,
target, and level when setting expectations on `enter`, `exit`, and
`drop_span`. This is not an issue for `tracing-mock`'s original (and
still primary) use case, which is to test `tracing` itself. However,
when testing the tracing instrumentation in library or application code,
this can be a limitation.
For example, when testing the instrumentation in tokio
(tokio-rs/tokio#6112), it isn't possible to set an expectation on which
task span is entered first, because the name, target, and level of those
spans are always identical - in fact, the spans have the same metadata
and only the field values are different.
To make differentiating different spans possible, `ExpectId` has been
introduced. It is an opaque struct which represents a `span::Id` and can
be used to match spans from a `new_span` expectation (where a `NewSpan`
is accepted and all fields and values can be expected) through to
subsequent `enter`, `exit`, and `drop_span` expectations.
An `ExpectedId` is passed to an `ExpectedSpan` which then needs to be
expected with `MockCollector::new_span`. A clone of the `ExpectedId` (or
a clone of the `ExpectedSpan` with the `ExpectedId` already on it) will
then match the ID assigned to the span to the other span lifecycle
expectations.
The `ExpectedId` uses an `Arc<AtomicU64>` which has the ID for the new
span assigned to it, and then its clones will be matched against that
same ID.
In future changes it will also be possible to use this `ExpectedId` to
match parent spans, currently a parent is only matched by name.
This change adds documentation to the tracing-mock `field` module and
all the public APIs within it. This includes doctests on all the methods
which serve as examples.
Additionally, the `field::msg` function (which constructs a field with
name "message" and the provided value) was moved to `expect::message`.
This is part of a unification of all expectation constructors inside the
`expect` module.
Refs: #539
Co-authored-by: David Barsky <me@davidbarsky.com>
This change adds documentation to the tracing-mock span module and all
the public APIs within it. This includes doctests on all the methods
which serve as examples.
Additionally, the validation on `ExpectedSpan` was improved so that it
validates the level and target during `enter` and `exit` as well as on
`new_span`.
The method `ExpectedSpan::with_field` was renamed to `with_fields`
(plural) to match the same method on `ExpectedEvent` (and because
multiple fields can be passed to it).
A copy-paste typo was also fixed in the documentation for
`ExpectedEvent::with_contextual_parent`.
Refs: #539
Co-authored-by: David Barsky <me@davidbarsky.com>
There has been interest around publishing tracing-mock to crates.io
for some time. In order to make this possible, it needs to be cleaned up.
There are some test utils in the `tracing-mock` crate which wouldn't
make sense to publish. They provide test futures that are needed in
multiple `tracing-*` crates, but would likely not be needed outside that
context.
This change moves that functionality into a separate `tracing-test`
crate, which should never be published to crates.io.
Refs: #539
Co-authored-by: David Barsky <me@davidbarsky.com>
There is an incompatibility with the version of Node available on our
test runners and wasm32 in Rust 1.82 (#3123).
To unblock the CI, this change pins Rust to 1.81 for the tests using the
`wasm32-unknown-unknown` target. This is the same strategy used in Tokio
to mitigate tokio-rs/tokio#6910 until a more permanent fix can be put in
place.
This change also bumps the MSRV on the `tracing-examples` crate from
1.63.0 to 1.64.0 to avoid triggering a lint about the MSRV after a
change in Tokio 1.41.0 which bumps the required Rust version for the
`try_join!` macro. The Tokio MSRV is 1.70 now, so needing this bump for
the examples seems reasonable.
## Motivation
`tracing-core` adds a dependency on `valuable` anytime the `std` (or `default`) feature is enabled even when `valuable` is not meant to be used. This was pointed out by [this comment](https://github.com/tokio-rs/tracing/pull/1608#discussion_r1626673415).
## Solution
Only add the feature dependency when something enables `valuable`.
This does not apply to `master` as `valuable` support there is always on.
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.
; Conflicts:
; examples/examples/map-traced-error.rs
When using `#[tracing::instrument]` and the `async unsafe` modifiers
the generated function read `unsafe async fn`, which is wrong. Corrected
the order and added a test.
Fixes: #2576
Signed-off-by: Gabriel Goller <g.goller@proxmox.com>
# 0.2.3 (November 13, 2023)
This release contains several new features. It also increases the
minimum supported Rust version (MSRV) to Rust 1.63.0.
## Added
- **rolling**: add option to automatically delete old log files (#2323)
- **non_blocking**: allow worker thread name to be configured (#2365)
- **rolling**: add a builder for constructing `RollingFileAppender`s
(#2227)
- **rolling**: add `Builder::filename_suffix` parameter (#2225)
- **non_blocking**: remove `Sync` bound from writer for `NonBlocking`
(#2607)
- **non_blocking**: name spawned threads (#2219)
## Fixed
- Fixed several documentation typos and issues (#2689, #2375)
## Changed
- Increased minimum supported Rust version (MSRV) to 1.63.0+ (#2793)
- Updated minimum `tracing-subscriber` version to
[0.3.18][subscriber-v0.3.18] (#2790)
[subscriber-v0.3.18]:
https://github.com/tokio-rs/tracing/releases/tag/tracing-subscriber-0.3.18
This branch _should_ fix the CI issues caused by https://github.com/tkaitchuck/aHash/issues/163.
(We can't move to 0.8.5 for MSRV reasons.)
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
