# 0.1.30 (October 6, 2022)
This release of `tracing-core` adds a new `on_register_dispatch` method
to the `Subscriber` trait to allow the `Subscriber` to perform
initialization after being registered as a `Dispatch`, and a
`WeakDispatch` type to allow a `Subscriber` to store its own `Dispatch`
without creating reference count cycles.
### Added
- `Subscriber::on_register_dispatch` method ([#2269])
- `WeakDispatch` type and `Dispatch::downgrade()` function ([#2293])
Thanks to @jswrenn for contributing to this release!
[#2269]: https://github.com/tokio-rs/tracing/pull/2269
[#2293]: https://github.com/tokio-rs/tracing/pull/2293
## Motivation
This fixes a discrepancy in the `tracing-opentelemetry` docs for the new
MetricsLayer. The docs refer to `value.` as a way to collect discrete
data point, but this doesn't match any of the prefix constant mentioned
in the same file.
```rust
const METRIC_PREFIX_MONOTONIC_COUNTER: &str = "monotonic_counter.";
const METRIC_PREFIX_COUNTER: &str = "counter.";
const METRIC_PREFIX_HISTOGRAM: &str = "histogram.";
```
## Solution
This fixes the documentation and test by referring to `histogram.`
instead of `value.`.
## Motivation
Currently, when using the `Layer` impl for `Option<S: Layer<...>>`, the
`Layer::max_level_hint` returns `Some(LevelFilter::OFF)`. This was
intended to allow totally disabling output in the case where a
`Subscriber` is composed entirely of `None` `Layer`s. However, when
other `Layer`s *do* exist but return `None` from their `max_level_hint`
implementations to indicate that they don't care what the max level is,
the presence of a single `None` layer will globally disable everything,
which is not the wanted behavior.
Fixes#2265
## Solution
This branch introduces a special downcast marker that can be used to
detect when a `Layer` in a `Layered` is `None`. This allows the
`pick_level_hint` method to short-circuit when a `Layer` implementation
which is `None` returns `Some(LevelFilter::OFF)` from its
`max_level_hint` if the other half of the `Layered` is not `None`. The
tests I added should be pretty thorough!
Additionally, the downcast marker is special-cased in the `reload`
`Layer`. Normally, this `Layer` doesn't support downcasting, but it can
in the case of the special marker value.
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
`tracing-appender` does not have `Rotation` based on size yet. Also, it
doesn't have the feature of keeping the most recent `N` log files
I believe the second feature is more easy to implement, and also will
partially solve the `Rotation` based on size problem. Because people may
choose `hourly` or `daily` rotation based on their needs, and put an
extra boundary of `keep the last 5 files` for example. Of course it
won't handle all the edge cases for `Rotation` based on size. But it
will cover most of the scenarios. And also, it is a good feature to have
on its own :)
## Solution
Introduce another field called `max_files: Option<usize>` to the `Inner`
of `RollingFileAppender` struct. I managed to did not touch any of the
existing functions, so it **WON'T BE A BREAKING CHANGE**. Yay :)
The solution is, whenever the rotation should happen, the
`refresh_writer()` is called. So I embed the following logic into that
function:
1- check the log folder and detect the log files 2- if there are more
log files than the `max_files` amount 3- store the filenames in a
vector, and sort them by their dates (dates are already present in the
filename) 4- keep deleting the oldest ones, till we have desired amount
of log files in the log folder
P.S. this PR was opened before, but got closed since it would be easier
for the maintainers to target `master` branch instead of `v0.1.x` Also,
@CBenoit contributed to this PR, it would be great to give credit to him
:)
Co-authored-by: Benoît Cortier <bcortier@proton.me>
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
Allows `Subscriber`s and `Layer`s to stash their own `Dispatch` without
causing a memory leak.
## Motivation
Resolves a shortcoming of #2269: that it's impossible for `Subscriber`s
or `Layer`s to stash a copy of their own `Dispatch` without creating a
reference cycle that would prevent them from being dropped.
## Solution
Introduces `WeakDispatch` (analogous to `std::sync::Weak`) that holds a
weak pointer to a `Subscriber`. `WeakDispatch` can be created via
`Dispatch::downgrade`, and can be transformed into a `Dispatch` via
`WeakDispatch::upgrade`.
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
The `async_fn` test file in `tracing-attributes` contains several
functions that exist just to test whether they _compile_, rather than
make assertions about their behavior. Because these functions are never
called, they (naturally) emit dead code warnings.
This commit adds `#[allow(dead_code)]` to the compilation tests, plus a
comment explaining why we do this.
The error messages for these tests appear to have changed a bit with
Rust 1.64. This commit includes changes to the `.stderr` file after
running the tests with `TRYBUILD=overwrite`, in order to update the
expected output for the latest Rust.
## Motivation
`bare_trait_objects` lint will become a hard error in Rust 2021.
While tracing is still using Rust 2018, `bare_trait_objects` is a
warning in the MSRV and `dyn` keyword is recommended.
## Solution
Replace all `&Value` with `&dyn Value` in macro expansions.
One can want to have an event added from outside context of a span,
especially in an async code (e.g. between polls of the future, or
between polling multiple futures instrumented with that span). Then it
is expected that the event will be attached indeed to the span specified
as the parent and not the contextual one.
Fixes: #2295
See #2295
Fixes#2280
## Motivation
I've implemented an alternative to [`tracing-wasm`] to fix some issues
that I had when using it (most are open as longer time bug reports, no
need to recount them here). It should be more up to date with the
current tracing framework and, being layer based, is easier to compose
with other subscribers, e.g. supports formatting and timing on event
logs out of the box.
## Solution
Add the [`tracing-web`] crate to the list of related crates.
[`tracing-wasm`]: (https://github.com/storyai/tracing-wasm)
[`tracing-web`]: https://crates.io/crates/tracing-web/
The `on_register_dispatch` method is invoked when a `Subscriber` is
registered as a `Dispatch`. This method should be overridden to
perform actions upon the installation of a subscriber/layer;
for instance, to send a copy of the subscriber's `Dispatch` to a
worker thread.
I just saw this warning when trying to debug something in Miri:
```
warning: some trace filter directives would enable traces that are disabled statically
| `miri::tls=trace` would enable the TRACE level for the `miri::tls` target
= note: the static max level is `info`
= help: to enable DEBUG logging, remove the `max_level_info` feature
```
I spent 10min figuring out why the `log` crate is doing this (Miri is
using env-logger for logging), until I realized that this error actually
originates from inside rustc, which I guess uses `tracing`. It would
have helped if the error message would say which crate is even talking
to me here. :)
## Motivation
Return type errors on instrumented async functions are a bit vague,
since the type error originates within the macro itself due to the
indirection of additional `async {}` blocks generated in the proc-macro
(and due to the way that inference propagates around in Rust).
This leads to a pretty difficult to understand error. For example:
```rust
#[instrument]
async fn foo() -> String {
""
}
```
results in...
```
error[E0308]: mismatched types
--> src/main.rs:1:1
|
1 | #[tracing::instrument]
| ^^^^^^^^^^^^^^^^^^^^^^- help: try using a conversion method: `.to_string()`
| |
| expected struct `String`, found `&str`
```
## Solution
Installs a fake `return` statement as the first thing that happens in
the auto-generated block of an instrumented async function.
This causes the coercion machinery within rustc to infer the right
return type (matching the the outer function) eagerly, as opposed to
after the `async {}` block has been type-checked.
This will cause us to both be able to point out the return type span
correctly, and properly suggest fixes on the expressions that cause the
type mismatch.
After this change, the example code above compiles to:
```
error[E0308]: mismatched types
--> src/main.rs:3:5
|
3 | ""
| ^^- help: try using a conversion method: `.to_string()`
| |
| expected struct `String`, found `&str`
|
note: return type inferred to be `String` here
--> src/main.rs:2:20
|
2 | async fn foo() -> String {
| ^^^^^^
```
## Motivation
Support the latest OpenTelemetry specification.
## Solution
Update `opentelemetry` to the latest `0.18.x` release. Breaking changes
in the metrics spec have removed value recorders and added histograms so
the metrics layer's `value.` prefix has been changed to `histogram.` and
behaves accordingly. Additionally the `PushController` configuration for
the metrics layer has been simplified to accept a `BasicController` that
can act in either push or pull modes. Finally trace sampling in the
sdk's `PreSampledTracer` impl has been updated to match the sampling
logic in https://github.com/open-telemetry/opentelemetry-rust/pull/839.
* Update MSRV to 1.56
* Update examples
* Fix async-trait dep
* Update msrv action
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
# 0.1.29 (July 29, 2022)
This release of `tracing-core` adds `PartialEq` and `Eq` implementations
for metadata types, and improves error messages when setting the global
default subscriber fails.
### Added
- `PartialEq` and `Eq` implementations for `Metadata` ([#2229])
- `PartialEq` and `Eq` implementations for `FieldSet` ([#2229])
### Fixed
- Fixed unhelpful `fmt::Debug` output for
`dispatcher::SetGlobalDefaultError` ([#2250])
- Fixed compilation with `-Z minimal-versions` ([#2246])
Thanks to @jswrenn and @CAD97 for contributing to this release!
[#2229]: https://github.com/tokio-rs/tracing/pull/2229
[#2246]: https://github.com/tokio-rs/tracing/pull/2246
[#2250]: https://github.com/tokio-rs/tracing/pull/2250
## Motivation
When a global default dispatcher has already been set, the
`dispatch::set_global_default` function fails with a
`SetGlobalDefaultError`. The `fmt::Display` impl for this type includes
a message explaining that the error indicates that a global default has
already been set, but the `fmt::Debug` impl is derived, and just looks
like this:
```
SetGlobalDefaultError { _no_construct: () }
```
which isn't particularly helpful.
Unfortunately, when `unwrap()`ping or `expect()`ing a `Result`, the
`fmt::Debug` implementation for the error type is used, rather than
`fmt::Display`. This means that the error message will not explain to
the user why setting the global default dispatcher failed, which is a
bummer.
## Solution
This branch replaces the derived `Debug` impl with a manually
implemented one that prints the same message as the `Display` impl, but
formatted like a tuple struct with a single string field. This avoids
emitting `Debug` output that's *just* a textual human-readable message,
rather than looking like Rust code, but ensures the message is visible
to the user when writing code like
```rust
tracing::dispatch::set_global_default(foo).unwrap();
```
The mesasge now looks like:
```
SetGlobalDefaultError("a global default trace dispatcher has already been set")
```
which should be a bit easier to debug.
## Motivation
Like for `Subscriber` and `Layer`, allow per-layer `Filter`s to filter
based on event fields.
## Solution
Add `Filter::event_enabled`, plumb it through the combinator
implementations, and call it from `Filtered`.
The bit I'm the least confident about is the check in `Registry`'s
implementation, but I *think* it matches what `event` is doing and
everything seems to function correctly.
## Motivation
I've wanted to serialize fieldset of current span.
## Solution
Expose already existing `SerializeFieldSet` for users by implementing `AsSerde` for `FieldSet`.
## Motivation
This makes it possible to fully "override" some base `Targets` filter
with another (e.g. user-supplied) filter. Without some way to obtain the
default, only explicit targets can be overridden (via `IntoIter` and
friends).
See also https://github.com/tokio-rs/tracing/issues/1790#issuecomment-999739222
## Solution
We can add a method to `Targets` that filters the underlying
`DirectiveSet` for the default directive. This works because
`DirectiveSet::add` will replace directives with the same
`target`/`field_names`, which is always `None`/`vec![]` for the
directive added by `with_default` (and in fact we are only concerned
with `target`, since no other `Targets` API allows adding directives
with a `None` target).
Ideally the method would be named `default`, corresponding to
`with_default`, however this conflicts with `Default::default` and so
would be a breaking change (and harm ergonomics). `default_level` seemed
a better name than `get_default`, since "getters" of this style are
generally considered unidiomatic<sup>[citation needed]</sup>.
Example usage:
```rust
let mut filter = Targets::new().with_target("some_module", LevelFilter::INFO);
// imagine this came from `RUST_LOG` or similar
let override: Targets = "trace".parse().unwrap();
// merge the override
if let Some(default) = override.default_level() {
filter = filter.with_default(default);
}
for (target, level) in override.iter() {
filter = filter.with_target(target, level);
}
```
Closes#1790
In the upstream `opentelemetry` crate, the `trace` and `metrics`
features are gated by separate feature flags. This allows users who are
only using OpenTelemetry for tracing, or who are only using it for
metrics, to pick and choose what they depend on.
Currently, the release version of `tracing-opentelemetry` only provides
tracing functionality, and therefore, it only depends on `opentelemetry`
with the `trace` feature enabled. However, the metrics support added in
#2185 adds a dependency on the `opentelemetry/metrics` feature. This is
currently always enabled. We should probably follow the same approach as
upstream `opentelemetry`, and allow enabling/disabling metrics and
tracing separately.
This branch adds a `metrics` feature to `tracing-opentelemetry`, and
makes the `MetricsLayer` from #2185 gated on the `metrics` feature.
This feature flag is on by default, like the upstream
`opentelemetry/metrics` feature, but it can be disabled using
`default-features = false`.
We should probably do something similar for the tracing components of
the crate, and make them gated on a `trace` feature flag, but adding a
feature flag to released APIs is not semver-compatible, so we should
save that until the next breaking release.
Motivation:
Currently, there is no way to publish metrics via tracing.
Solution:
Update the tracing-opentelemetry crate to publish metrics for event
fields that contain specific prefixes in the name.
Right now, we lazily instantiate and store one metrics object
per-callsite, but a future improvement that we should add to tracing
itself is the ability to store data per-callsite, so that we don't have
to do a HashMap lookup each time we want to publish a metric.
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
Co-authored-by: David Barsky <me@davidbarsky.com>
## Motivation
The `RollingFileAppender` currently only supports a filename suffix. A
lot of editors have support for log files using the `.log` extension. It
would be nice to be able to configure what gets added after the date.
## Solution
- Add a `Builder::filename_suffix` method, taking a string.
- If the string is non-empty, this gets appended to the filename after
the date.
- This isn't an `AsRef<Path>` because it's not supposed to be a `Path`
- Update the date appending logic to handle cases when the suffix or
prefix is empty
- Split each part with a `.` so the final output would be
`prefix.date.suffix`
- Make sure to remove unnecessary `.` when a prefix or suffix is empty
- Add tests related to those changes
## Notes
It would probably be nicer to simply have a completely configurable file
name format, but I went with the easiest approach that achieved what I
needed.
Closes#1477
## Motivation
Previously the documentation for `fmt::init()` was misleading. It stated
that it was shorthand for `fmt().init()`. This lead to confusion as
users would expect the same behavior from both. However `fmt::init()`
would, whether you used the env-filter feature or not, rely on RUST_LOG
to set the tracing level. `fmt().init()` does not do this and it must be
set with a specific configuration via `with_env_filter`.
## Solution
The documentation has been updated to no longer state that it is 1:1
shorthand for the other. The documentation now specifically points out
that you must be using the `env-filter` feature and gives a correct
example to mimic the `fmt::init()` behavior using `fmt().init()`.
Fixes#2217Fixes#1329
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Fix minimal-versions failure.
## Solution
Upgrade all the dependencies to their most recent semver-compatible
version, adjusting back down as necessary for MSRV.
Essentially a cherry-pick of #2231, but redone by hand.
## Tests
- `cargo minimal-versions msrv verify -- cargo check --all-features`
- `cargo minimal-versions msrv verify -- cargo check --no-default-features`
## Methodology
- `cargo update && cargo upgrade --to-lockfile`
- Identify [a bug](https://github.com/killercup/cargo-edit/issues/750) and manually resolve it
- loop; upgrade transitive deps
- `cargo minimal-versions check --all-features`
- Identify failing dep
- `cargo minimal-versions tree -i dep --all-features`
- Find the closest dependency leading to pulling in `dep`
- `cargo add fixdep --optional` to force a more recent more-minimal-versions-correct version
- loop; downgrade to msrv
- `cargo minimal-versions msrv verify -- cargo check --all-features`
- Identify failing dep
- `cargo minimal-versions tree -i dep --all-features`
- Find the version that supports MSRV from lib.rs
- `cargo upgrade dep@msrv`
Motivation:
When `Format_event::format_event(...)` returns an error, we are
currently silently dropping that
Event. https://github.com/tokio-rs/valuable/issues/88 explains one
such case in which this was encountered (due to a bug in
valuable-serde). We want to be made aware whenever an Event is dropped.
Solution:
Write to the Writer with an error message to let the user know that
we were unable to format a specific event. If writing to the Writer fails,
we fall back to writing to stderr. We are not emitting an actual tracing
Event, to avoid the risk of a cycle (the new Event could trigger the
same formatting error again).
Resolves#1965.
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
Co-authored-by: David Barsky <me@davidbarsky.com>
# 0.3.15 (Jul 20, 2022)
This release fixes a bug where the `reload` layer would fail to pass
through `max_level_hint` to the underlying layer, potentially breaking
filtering.
### Fixed
- **reload**: pass through `max_level_hint` to the inner `Layer`
([#2204])
Thanks to @guswynn for contributing to this release!
[#2204]: https://github.com/tokio-rs/tracing/pull/2204
A `FieldSet` is equal to another `FieldSet` if they share the same
callsite and fields (provided in the same order). This ensures
that a `Field` applicable to one `FieldSet` is applicable to any
equal `FieldSet`. A `Metadata` is equal to another `Metadata` if
all of their contained metadata is exactly equal.
This change manually re-implements `PartialEq` and `Eq` for
`Metadata` and `FieldSet` to define their equality strictly in
terms of callsite equality. In debug builds, the equality of
these types' other fields is also checked.
Documentation is added to both `Metadata` and `FieldSet`
explaining this behavior.
The expectation that, in a well-behaving application, `Metadata`
and `FieldSet`s with equal callsites will be otherwise equal is
documented on `Callsite::metadata`. This is not a breaking change,
as previous releases did not define equality for `Metadata` or
`FieldSet`. The `Callsite` trait remains safe, as this expectation
is not (yet) a safety-critical property.
## Motivation
Several currently open PRs, such as #2225 and #2221, add new
configuration parameters to the rolling file appender in
`tracing-appender`. The best way to add new optional configuration
settings without breaking existing APIs or creating a very large number
of new constructors is to add a builder interface.
## Solution
Since a number of PRs would all need to add the builder API, introducing
potential conflicts, this branch _just_ adds the builder interface
without adding any new configuration options. Once this merges, the
existing in-flight PRs can be rebased onto this branch to use the
builder interface without conflicting with each other.
Also, the `Builder::build` method is fallible and returns a `Result`,
rather than panicking. This is a relatively common pattern in Rust ---
for example, `std:🧵:Builder::spawn` returns a `Result` if a new
thread cannot be spawned, while `std:🧵:spawn` simply panics. This
allows users to handle appender initialization errors gracefully without
breaking the API of the existing `new` constructor.
Fixes#1953
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Previously, using `record("x", "y")` would give an error:
```
error[E0277]: the size for values of type `str` cannot be known at compilation time
--> src/main.rs:3:22
|
243 | span.record("x", "y");
| ^^^^^^ doesn't have a size known at compile-time
|
= help: the trait `Sized` is not implemented for `str`
note: required by a bound in `Span::record`
--> /home/jnelson/.local/lib/cargo/registry/src/github.com-1ecc6299db9ec823/tracing-0.1.32/src/span.rs:1184:30
|
1184 | pub fn record<Q: ?Sized, V>(&self, field: &Q, value: &V) -> &Self
| ^ required by this bound in `Span::record`
```
Now it works fine, as tested by the doc-example.
This doesn't break any existing code, because there's a generic `impl<T: Value> Value for &T`: https://docs.rs/tracing/0.1.35/tracing/trait.Value.html#impl-Value-for-%26%27a%20T
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
I find it useful when debugging applications with lots of threads to
easily identity them by their names.
## Solution
Just name the thread as other crates such as `sentry-rust` are doing.
Co-authored-by: Guillaume Desmottes <guillaume@desmottes.be>
Motivation:
When a user clicks they they may accidentally get an old version of the
crate. Its also out of sync with the current main readme.
Solution:
removed the hard coded links
Older versions use node 12 which is no longer supported (end-of-life on April 30, 2022). Also, @main/@master is not very good as they may run into unreleased breaking changes.
## Motivation
When using a `reload` layer, the fast-path current level check doesn't
work, as the `max_level_hint` is just `None`, which `rebuild_interest`
interprets as `TRACE`
## Solution
Pass through to the underlying layer/filter. On poisons, when already
panicking, just return `None`
# 0.1.22 (July 1, 2022)
This release fixes an issue where using the `err` or `ret` arguments to
`#[instrument]` along with an overridden target, such as
```rust
#[instrument(target = "...", err, ret)]
```
would not propagate the overridden target to the events generated for
errors/return values.
### Fixed
- Error and return value events generated by `#[instrument(err)]` or
`#[instrument(ret)]` not inheriting an overridden target (#2184)
- Incorrect default level in documentation (#2119)
Thanks to new contributor @tbraun96 for contributing to this release!
# 0.17.4 (July 1, 2022)
This release adds optional support for recording `std::error::Error`s
using OpenTelemetry's [semantic conventions for exceptions][exn-semconv].
### Added
- `Layer::with_exception_fields` to enable emitting `exception.message`
and `exception.backtrace` semantic-convention fields when an `Error`
is recorded as a span or event field ([#2135])
- `Layer::with_exception_field_propagation` to enable setting
`exception.message` and `exception.backtrace` semantic-convention
fields on the current span when an event with an `Error` field is
recorded ([#2135])
Thanks to @lilymara-onesignal for contributing to this release!
[thread-semconv]: https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/exceptions/
[#2135]: https://github.com/tokio-rs/tracing/pull/2135
The second invocation would always fail, since that version had already
been published. This command failing would cause the script to exit with
an error, and thus fail to push the release tag.
This commit fixes this by removing the second `cargo publish`.
# 0.3.14 (Jul 1, 2022)
This release fixes multiple filtering bugs in the `Layer`
implementations for `Option<impl Layer>` and `Vec<impl Layer>`.
### Fixed
- **layer**: `Layer::event_enabled` implementation for `Option<impl
Layer<S>>` returning `false` when the `Option` is `None`, disabling
all events globally ([#2193])
- **layer**: `Layer::max_level_hint` implementation for `Option<impl
Layer<S>>` incorrectly disabling max level filtering when the option
is `None` ([#2195])
- **layer**: `Layer::max_level_hint` implementation for `Vec<impl
Layer<S>>` returning `LevelFilter::ERROR` rather than
`LevelFilter::OFF` when the `Vec` is empty ([#2195])
Thanks to @CAD97 and @guswynn for contributing to this release!
[#2193]: https://github.com/tokio-rs/tracing/pull/2193
[#2195]: https://github.com/tokio-rs/tracing/pull/2195
## Motivation
Currently, the `tracing-opentelemetry` docs indicate that the support
for OpenTelemetry's exception semantic conventions added in #2135 is
enabled by default. However, this is not the case --- this feature was
changed to opt-in rather than opt-out prior to merging PR #2135.
## Solution
This branch updates the docs to state that these features are disabled
by default, rather than enabled by default.
