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>
When using a function annotated with `#[instrument]` it parses the
parameters of the function and records them either using `Value` or
using `std::fmt::Debug`. There were a few types that implement `Value`
but were missing the RecordTypes array. Added them + a unit test for a
single one.
Fixed: #2775
The `from_env` and `try_from_env` methods on the builder had the same documentation. This change updates their docs to correctly describe their difference in behavior.
## Motivation
Make the docs more clear, so that users need not look at the source to understand the difference between these two functions.
## Solution
Updated the docs
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
When a user has a crate named `core`, it can cause issues
because our crates import from `::core::*`. Now we are
importing from `$crate::__macro_support::*` and there will
be no more name clashes.
These docs were updated (in response to #1669), but the "or equal to"
phrase should have been moved to the other case.
Fixes: #1993
## Motivation
When these docs were updated in response to #1669, they were updated
incompletely (a level that is equal to a filter is _enabled_, not
_disabled_) and therefore remained incorrect.
## Solution
The docs were updated, moving the "or equal to" phrase to the other
case.
## Motivation
`NonBlocking` from `tracing-appender` wraps a writer and requires that
writer to implement `Sync` (among other bounds). However it is not clear
why this bound is necessary in first place: this writer is sent to a
dedicated thread and never used directly concurrently.
#1934 demonstrates that it is a real problem for some people. Also at my
current work we hit this issue as well when a third-party writer did not
implement `Sync`. Our workaround was to wrap that writer in our own type
and manually implement `Send` and `Sync` for it. Needless to say that it
is more a hack than a proper solution.
## Solution
Remove `Sync` bound in relevant places. Yep, that simple. Probably
having it in first place was just an oversight.
Closes#1934
There was an error when backporting #1378 (here: #1418) and a trailing
dot (.) was forgotten (which was breaking the link). Fixed also the link to
`std::fmt::Debug`.
Removing the `env_logger` feature in order to address GHSA-g98v-hv3f-hcfr.
In addition, this PR also removes the deprecated `trace_logger` module, in
preparation for an upcoming v0.2.0 of `tracing-log`.
For additional details on the approach, please refer to #2750. Note that this
PR depends on #2770, so this PR will temporarily have more commits
than intended.
---------
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
# 0.1.40
This release fixes a potential stack use-after-free in the
`Instrument::into_inner` method. Only uses of this method are affected
by this bug.
### Fixed
- Use `mem::ManuallyDrop` instead of `mem::forget` in
`Instrument::into_inner` (#2765)
[#2765]: https://github.com/tokio-rs/tracing/pull/2765
Thanks to @cramertj and @manishearth for finding and fixing this issue!
When a custom macro "format_args" is defined, macros such as
`tracing::warn`, `tracing::debug`, etc. will fail. Adding the
full path `::core::format_args!` to the calls fixes this.
Fixes: #2721
# 0.1.27 (October 13, 2023)
### Changed
- Bump minimum version of proc-macro2 to 1.0.60 (#2732)
- Generate less dead code for async block return type hint (#2709)
### Fixed
- Fix a compilation error in `#[instrument]` when the `"log"`
feature is enabled (#2599)
