This is useful when using `EnvFilter` for multiple identical per-layer
filters, as well as with clap and similar libraries that have `Clone`
bounds.
We generally expect users to be cloning an `EnvFilter` before attaching it
to a subscriber, rather than cloning `EnvFilters` that are already
attached. Because of this, we reset all the accumulated dynamic state
when cloning. This means that some spans and callsites might be missed
when an already-attached `EnvFilter` is cloned, but the presence of the
dynamic state mean that detaching and attaching `EnvFilter`s to existing
subscribers (e.g. with `reload`) already doesn't work very well. This
isn't a new class of problem.
There was a previous implementation of this in #2398, that shared the
dynamic state between all cloned filters behind an `Arc`. I chose
not do go for that approach because it causes inconsistencies if the
cloned filters are attached to different subscribers.
Fixes: #2360
## Motivation
While configuring tracing-appender, I wanted to specify a weekly log
rotation interval. I was unable to do so, as the largest rotation
interval was daily.
## Solution
Before my introduction of weekly log rotation, rounding the current
`OffsetDateTime` was straightforward: we could simply keep the current
date and truncate part or all of the time component. However, we cannot
simply truncate the time with weekly rotation; the date must now be
modified.
To round the date, we roll logs at 00:00 UTC on Sunday. This gives us
consistent date-times that only change weekly.
`self` and `other` are references, and the `ptr::eq()` call intends to
determine if they designate the same object. Putting them behind another
level of reference will always return `false`, as those short-lived
references will be compared instead.
It can be useful to have a TestWriter that does not log to stdout but
stderr instead. For example, that allows for potentially easier
filtering of tracing output (because the remaining output of, say, cargo
test goes to stdout) or to mirror behavior of env_logger, which by
default logs to stderr.
Introduce the TestWriter::with_stderr() constructor to enable such
usage. The default is left unchanged.
Co-authored-by: David Barsky <me@davidbarsky.com>
This example demonstrates how to use the `tracing-subscriber` crate's
`EnvFilter` type to filter log messages based on their metadata. The
example provides a text area where users can input an environment filter
string, and displays the log messages that would be captured by that
filter.
There is a report in #3174 that even in release mode, building the regex
used to parse `EnvFilter` directives can take a relatively large amount
of time (600us).
This change replaces the `regex` based parsing of the directives with a
state machine implementation that is faster and also easier to reason
about.
Fixes: #3174
This PR expands [`portable-atomic`](https://docs.rs/portable-atomic/)
utilisation within Tracing, improving platform support without breaking
the existing public API.
## Motivation
Since #3199 was merged, it's now possible to bring more tracing crates
to atomically challenged platforms through `portable-atomic`.
Additionally, CI is not currently setup to ensure this feature behaves
as expected (allowing compilation on platforms with incomplete atomic
support).
## Solution
- Added `portable-atomic` support to:
- `tracing`
- `tracing-futures`
- `tracing-serde`
- `tracing-subscriber`
- Added `no_std` support to:
- `tracing-macros`
- `tracing-futures`
- Added CI task to catch regressions in `portable-atomic` _and_ `no_std`
support.
## Notes
- A `critical-section` feature is also added to make CI testing and
usage of `tracing`/etc. on atomically challenged platforms simpler.
- No additional dependencies are included in this PR, optional or
otherwise. Instances of including `portable-atomic` as a dependency
only occur when it would have already been included transitively via
`tracing-core`'s `portable-atomic-util` dependency.
- I checked all instances of replacing `core::sync::atomic` with
`portable-atomic` to ensure the public API was unaffected. As such,
this is not a breaking change, since it simply adds `portable-atomic`
and `critical-section` features.
## Motivation
I want to use `bevy_reflect` on `no_std` devices. This platform has alloc,
but not atomics, so `alloc::sync` is missing. `bevy_relflect` has a hard
depency on `tracing`, and I'd like to use tracing on this platform also.
Want to use tracing-core on `no_std` devices like rp2040
without hardware atomics
## Solution
- Added `portable-atomic-util` as an optional dependency
gated behind a new feature, `portable-atomic` to
`tracing-core`
- When `portable-atomic` is enabled, switched uses of
`Arc` and `Weak` away from `alloc::sync` to
`portable_atomic_util`.
- Added workaround for a lack of support for
[unsized coercion](https://github.com/rust-lang/rust/issues/18598)
in custom types. I've included a comment linking to this issue
explaining the missing functionality.
Fixes#3173
## Motivation
Currently, Span.record_all() is part of the public API and accepts
ValueSet as a parameter. However, constructing a ValueSet is both
verbose and undocumented, making it not so practical.
## Solution
To make recording multiple values easier, we introduce a new macro:
record_all!, which wraps the Span.record_all() function.
As we don't intend anyone to call Span.record_all() directly, we hide
it from the documentation. We reference the new macro from Span.record()
doc comment instead.
The new record_all! macro supports optional formatting sigils % and ?,
ensuring a consistent DevEx with the other value-recording macros.
Co-authored-by: Hayden Stainsby <hds@caffeineconcepts.com>
We had some broken link formatting in the `tracing-journald` docs which
clippy picked up (the text looked like a link definition, but wasn't
meant to be).
The incorrect links have now been corrected. They have to link to the
`tracing-core` crate because `tracing-journald` doesn't depend on
`tracing` directly.
Fixes for a broken link in the `tracing-subscriber` main page and
correcting the link to `Collect` from `tracing-log` (which also doesn't
depend on `tracing` directly) were also included.
There was only a single case of the new `needless_as_bytes` lint which
was triggered and needed to be fixed.
There was also a "UI" test in `tracing-attributes` that needed to be
updated because the error text has changed (it gives more details of
course).
## Motivation
The current behaviour of `DefaultVisitor` is that it will write
padding even if it is going to skip writing a value, which results
in extraneous padding being added when values are skipped
by the `tracing-log` integration.
## Solution
With this change, `DefaultVisitor` will only insert padding if it is
actually going to write a value.
Closes: #2979
@jonhoo recorded a great resource about the crate's inner
workings and included practical suggestions about patterns
to follow when annotating one's code.
I added the link to the YouTube video under the "Talks" header
as that seemed appropriate enough.
## Motivation
I was checking the example from `/examples/` and saw that
some of the module names were incorrect in README, so I
fixed them.
## Solution
Changed the incorrect name to the correct name.
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.
## 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
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.
## Solution
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
## Motivation
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.
## Solution
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.
## 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.
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.
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.
It is not uncommon that users who are new to tracing look at the
examples in the `master` branch of the repository and find that they
don't compile. This is because they are examples which compile with the
code from the master branch, which is for the as yet unreleased tracing
0.2.0 ecosystem.
Users should instead go to the `v0.1.x` branch to find examples
compatible with the crates published on crates.io.
This change adds a doc-comment to the beginning of every example file
informing the user of this fact and suggesting that they check out the
`v0.1.x` branch instead.
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>
## Motivation
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.
## Solution
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
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.
## Motivation
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¹.
## Solution
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
## Motivation
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.
## Solution
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.
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
