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>
## 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
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)
Currently, the `hyper_echo` example uses the `tracing-log` env logger
support for some weird reason. I believe this is due to Hyper previously
using `log` rather than `tracing`. However, `hyper` now emits native
`tracing` diagnostics, so all the `env_logger` nonsense can just be
removed from the example.
This branch does that.
; Conflicts:
; examples/Cargo.toml
; examples/examples/hyper-echo.rs
## Motivation
As seen here #2512 and #2223. Previously pr'ed here #2525, but no progress has
been made there for quite some. I have applied the suggested changes. Not sure
the formatting of the doc is sufficient or otherwise correct
## Solution
Make the `format::Writer::new()` function public. I don't see any obvious
trade-offs, but I am not familiar with the larger direction of
tracing/subscriber, so I may be wrong.
Closes #2512Closes#2223
Co-authored-by: Cephas Storm <cephas.storm@borisfx.com>
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
Clippy doesn't like the redefinition of a binding with itself. I don't
think this was necessary for the bug we were reproducing here (as the
error test doesn't do this), so I removed it.
The latest Clippy emits warnings for uses of `unwrap_or_else` with
functions that return a type's `Default::default` value, such as
`.unwrap_or_else(String::new)`. Clippy would prefer us to use
`unwrap_or_default` instead, which does the same thing.
This commit fixes the lint. Personally, I don't really care about this,
but it makes the warning go away...
The package `atty`, a dependent of `env_logger` < 0.10, has a RUSTSEC advisory
raised against it (GHSA-g98v-hv3f-hcfr). This branch updates `env_logger` to
0.10 to fix this issue.
It's currently awkward to have an optional per-layer filter.
Implement `Filter<L>` for `Option<F> where F: Filter<L>`, following the example
of `Layer`. A `None` filter passes everything through.
Also, it looks like Filter for Arc/Box doesn't pass through all the methods, so
extend the `filter_impl_body` macro to include them.
This also adds a couple of tests and updates the docs.
---------
Co-authored-by: David Barsky <me@davidbarsky.com>
Co-authored-by: Ryan Johnson <ryantj@fb.com>
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
As part of landing #2728, I noticed that the `-Zminimal-versions` check fails
due to proc-macro2 1.0.40 referencing a since-removed, nightly-only
feature (`proc_macro_span_shrink`). Since this change doesn't change the MSRV
of `proc-macro2` (or `tracing`, for that matter), this feels like a safe change
to make.
Issue https://github.com/tokio-rs/tracing/issues/2080 explains that it's not
possible to soundly use
[`tracing_subscriber::fmt::time::LocalTime`](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/time/struct.LocalTime.html)
in a multithreaded context. It proposes adding alternative time formatters that
use the [chrono crate](https://docs.rs/chrono/latest/chrono/) to workaround
which is what this PR offers.
A new source file 'chrono_crate.rs' is added to the 'tracing-subscriber'
package implementing `mod chrono_crate` providing two new tag types `LocalTime`
and `Utc` with associated `time::FormatTime` trait implementations that call
`chrono::Local::now().to_rfc3339()` and `chrono::Utc::now().to_rfc3339()`
respectively. Simple unit-tests of the new functionality accompany the
additions.
---------
Co-authored-by: David Barsky <me@davidbarsky.com>
Co-authored-by: Shayne Fletcher <shaynefletcher@meta.com>
I've found myself in the case where I wanted to have customized event field name
for different trait implementations. In fact, these implementations are
completely unrelated (in separate applications), so, in this use case, I find
more readable to have `foo="some_id"` and `bar=16` instead of `resource="foo"
value="some_id"` and `resource=bar value=16`
Because events only accept identifier or literal as field name, this is quite
cumbersome/impossible to do. A simple solution could be to make events accept
constant expression too; in my use case, I could then add a associated constant
to my trait.
This PR proposes a new syntax for using constant field names:
```rust
tracing::debug!({ CONSTANT_EXPR } = "foo");
```
This is the same syntax than constant expression, so it should be quite intuitive.
To avoid constant expression names conflict, internal variables of macro
expansion have been prefixed with `__`, e.g. `__CALLSITE`.
Co-authored-by: Joseph Perez <joseph.perez@numberly.com>
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
It's currently not possible to customize how messages will get send to journald.
This became apparent in #2425, where first a specific API got designed, but then
it was decided that users should not get restricted in only a subset of fields,
but should be able to simply choose by themselves what fields get set with what
values.
So in a sense, this is the successor/rework of #2425.
Allow custom fields to be set in tracing-journald.
- [x] How should we deal with fields that also get supplied by other options?
For example, setting `SYSLOG_IDENTIFIER` here and also setting
`.with_syslog_identifier()` will send said field twice, potentially with
differing values. Is that a problem?
- Answer: No, this is not a problem.
Closes#2425
## Motivation
The motivation is #1426. Currently, event names are set to a default
value of `event file:line`, which (1) doesn't allow for customization,
and (2) prevents events from working for some opentelemetry endpoints
(they often use the event name `exception` to designate something like a
panic).
## Solution
Went through the event macros, and added new parameterization that
allows for setting the `name`. In addition, added some comments, and
reordering, to make life a bit better for the next person that comes
along to edit those macros. Finally, added tests for the macro
expansion alongside the existing tests with a reasonable amount of
coverage (though, admittedly, more could be added for all of the macro
invocation types
Fixes#1426
## Motivation
Fixes: #1566
## Solution
This change removes the maximum of 32 fields limitation using const
generics.
Having this arbitrary restriction in place to prevent stack overflows
feels a little misplaced to me since stack size varies between
environments.
## Motivation
`#[tracing::instrument]` uses `unreachable!()` macro which needlessly
expands to panicking and formatting code. It only needs any `!` type.
## Solution
`loop {}` works just as well for a `!` type, and it crates less work for
the compiler. The code is truly unreachable, so the message would never
be useful. Rust used to be concerned about semantics of empty loops in
LLVM, but this [has been solved](https://reviews.llvm.org/D85393).
## Motivation
The `.folded` format expects a `;`-separated list of the stack function,
optionally followed up by a sample count.
The implementation before this commit added a blank space after each `;`
which made parsers, such as `inferno-flamegraph` mis-interpret the data.
Furthermore, normally one wouldn't expect the filename and line-number
in such stack trace.
## Solution
Remove white-space between `;` for the generated file and remove
filename and line-number by default.
