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.
## 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.
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.
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.
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>
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.
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.
As part of upgrading syn to 2.0 (e.g.,
https://github.com/tokio-rs/tracing/pull/2516), we need to bump the MSRV
to 1.56. As part of this PR, I've:
- Updated the text descriptions of what would be an in-policy MSRV bump
to use more recent versions of rustc. The _niceness_ of said version
numbers are purely coincidental.
- I've removed some of the exceptions made in CI.yml in order to support
some crates with a higher MSRV.
This PR removes tracing-opentelemetry to a dedicated repo located at
https://github.com/tokio-rs/tracing-opentelemetry. (Note that at time of
writing this PR, the new repo has not be made public). We're moving
tracing-opentelemetry to a dedicated repository for the following
reasons:
1. opentelemetry's MSRV is higher than that of `tracing`'s.
2. more importantly, the main `tracing` repo is getting a bit unweildy
and it feels unreasonable to maintain backports for crates that
integrate with the larger tracing ecosystem.
(https://github.com/tokio-rs/tracing-opentelemetry does not have the
examples present in this repo; this will occur in a PR that will be
linked from _this_ PR.)
## 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
## Motivation
Fix minimal-versions failure.
## Solution
Upgrade all the dependencies to their most recent semver-compatible
version, adjusting back down as necessary for MSRV.
## Context
[cargo-minimal-versions](https://lib.rs/crates/cargo-minimal-versions)
is wonderful. With this PR, the full repo passes under all of
- `cargo hack --workspace minimal-versions check --all-features`
- `cargo +1.49 hack --workspace --exclude tracing-appender
minimal-versions check --all-features`
- `cargo +1.53 hack -p tracing-appender minimal-versions check
--all-features`
- All of CI 😇
This patch adds a bit more context around why we are creating a smaller
scope for the spans, and also what happens when we call
`global::shutdown_tracer_provider()` (that comment was copied from
the`rust-opentelemetry` repo).
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
`Value` was already implemented for `dyn Error + 'static`, but rust
doesn't silently coerce trait objects. This means that passing an error
of type `dyn Error + Send + Sync + 'static` would not work. This is
related to #1308.
## Solution
Add impls for `dyn Error + …` variants for `Send`, `Sync`, and `Send +
Sync`. These extra impls just delegate to the existing `dyn Error +
'static` impl.
Also update one of the examples to use `dyn Error + Send + Sync` to
demonstrate that this works.
Refs: #1308
This updates all crates' MSRVs to 1.49 if they were not already greater
than that (`tracing-appender` is at 1.53). Rust 1.49+ is required to
update `parking_lot` to v0.12 (see #1878). Also, `futures-task` (which I
believe is only needed as a transitive dep) now needs 1.45+, so this
also fixes our CI build.
Because `tracing-opentelemetry` previously required 1.46.0, it had a
separate CI MSRV job. Since 1.49.0 is greater than 1.46.0, the separate
check for `tracing-opentelemetry` is no longer needed.
In the process, I removed deprecated uses of
`core::atomic::spin_loop_hint`, which is replaced with
`core::hint::spin_loop` in 1.49.
## Motivation
Support the latest OpenTelemetry specification.
## Solution
Update `opentelemetry` to the latest `0.17.x` release. Breaking changes
upstream in the tracking of parent contexts in otel's `SpanBuilder` have
necessitated a new `OtelData` struct to continue pairing tracing spans
with their associated otel `Context`.
## Motivation
Logging line numbers and file names can be useful for debugging. This
feature was suggested by #1326
## Solution
As per @hawkw's suggestions, fields were added on `Format`, along with
builder methods. Filename and line number information was gathered from
the `meta` variable.
The `Pretty` formatter already supports printing source locations, but
this is configured separately on the `Pretty` formatter rather than on
the `Format` type. This branch also changes `Pretty` to honor the
`Format`-level configurations and deprecates the `Pretty`-specific
method.
Fixes#1326Closes#1804
Co-authored-by: David Barsky <me@davidbarsky.com>
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Currently, `tracing-appender`'s `RollingFileAppender` does not implement
the `MakeWriter` trait. This means it can only be used by either
wrapping it in `NonBlocking`, or by wrapping it in a `Mutex`. However,
this shouldn't be strictly necessary, as `&File` implements `io::Write`.
It should thus only be necessary to introduce locking when we are in the
process of _rotating_ the log file.
## Solution
This branch adds a `MakeWriter` implementation for
`RollingFileAppender`. This is done by moving the file itself inside of
an `RwLock`, so that a read lock is acquired to write to the file. This
allows multiple threads to write to the file without contention. When
the file needs to be rolled, the rolling thread acquires the write lock
to replace the file. Acquiring the write lock is guarded by an atomic
CAS on the timestamp, so that only a single thread will try to roll the
file. This prevents other threads from immediately rolling the file
_again_ when the write lock is released.
I...should probably write tests for that, though.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This changes `tracing-subscriber` so that the `env-filter`, `json`,
and `chrono` features are not enabled by default, and instead require
users to opt in. This should significantly reduce the default
dependency footprint.
Of course, this is a breaking change, and therefore will be part of
`tracing-subscriber` v0.3.
Fixes#1258
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Currently, `tracing-subscriber` supports the `chrono` crate for
timestamp formatting, via a default-on feature flag. When this code was
initially added to `tracing-subscriber`, the `time` crate did not have
support for the timestamp formatting options we needed.
Unfortunately, the `chrono` crate's maintainance status is now in
question (see #1598). Furthermore, `chrono` depends on version 0.1 of
the `time` crate, which contains a security vulnerability
(https://rustsec.org/advisories/RUSTSEC-2020-0071.html). This
vulnerability is fixed in more recent releases of `time`, but `chrono`
still uses v0.1.
## Solution
Fortunately, the `time` crate now has its own timestamp formatting
support.
This branch replaces the `ChronoLocal` and `ChronoUtc` timestamp
formatters with new `LocalTime` and `UtcTime` formatters. These
formatters use the `time` crate's formatting APIs rather than
`chrono`'s. This removes the vulnerable dependency on `time` 0.1
Additionally, the new `time` APIs are feature flagged as an _opt-in_
feature, rather than as an _opt-out_ feature. This should make it easier
to avoid accidentally depending on the `time` crate when more
sophisticated timestamp formatting is _not_ required.
In a follow-up branch, we could also add support for `humantime` as an
option for timestamp formatting.
Naturally, since this removes existing APIs, this is a breaking change,
and will thus require publishing `tracing-subscriber` 0.3. We'll want to
do some other breaking changes as well.
Fixes#1598.
This adds a new `Span::or_current` method that returns the span it's
called on, if that span is enabled, or the current span if that span
is not enabled.
This should provide a more efficient alternative to writing code like
```rust
tokio::spawn(
future
.instrument(some_span)
.in_current_span()
);
```
since it doesn't wrap the future in two different spans which are
(potentially) both entered on polls. It's also a little more concise
to write, which (hopefully) will encourage people to use it instead
of the less efficient alternative.
`Span::or_current` may be useful in other cases as well.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This commit updates the `inferno-flame` example to use the `tempfile`
crate as a replacement
for the unmaintained `tempdir` crate.
Also, the previous version of the example output the flamegraph inside
the temporary directory. Since the temporary directory is cleaned up
when the program exits, this means the user can't actually look at the
flamegraph when running this example. I've changed the example to put the
flamegraph in the current working dir instead, so the user can look at
it.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This version includes patches for a couple of RUSTSEC advisories that
`cargo audit` is mad about. These aren't actually security-critical,
since the affected hyper versions are only used in examples, not in
actual`tracing` crates, but bumping makes `cargo audit` chill out. And
we should keep up to date regardless.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Currently, there are a few examples that include CLI argument parsing.
These currently use the `clap` crate. `clap` is one of the most flexible
and full-featured argument parsing libraries in Rust. However, or
perhaps *because* of this, `clap` is also a fairly heavy-weight
dependency which pulls in a lot of transitive deps.
We don't *need* most of `clap`'s features for the very simple argument
parsing in these examples. Therefore, this commit replaces `clap` with
`argh`, which is a much lighter dependency.
Also, `clap` is currently pulling a version of `bitflags` that breaks
our MSRV...
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Forward-port of #1460 to the 0.2.x (master) branch.
## Motivation
Fixes#1347
## Solution
Change the format from `err=message, err: source1` to `err=message
err.sources=[source1, source2, source3, ...]`, as suggested in
#1347 (comment)
(still leaving out the sources if there are none).
## Caveats
Haven't changed the JSON formatter, since I'm not really sure about how
to do that. The current format is `{.., "fields": {.., "err":
"message"}}`, disregarding the sources entirely.
We could change that to `{.., "fields": {.., "err": "message",
"err.sources": ["source1", "source2", "source3", ..]}}`, which would
keep backwards compatibility but looks pretty ugly.
Another option would be `{.., "fields": {.., "err": {"message":
"message", "sources": ["source1", "source2", "source3", ..]}}}` which
leaves room for future expansion.
Then again, that begs the question about why the first error is special,
so maybe it ought to be `{.., "fields": {.., "err": {"message":
"message", "source": {"message": "source1", "source": ..}}}}`.
But that style of linked list is pretty annoying to parse, so maybe it
ought to be flattened to `{.., "fields": {.., "err": [{"message":
"message"}, {"message": "source1"}, ..]}}`?
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
Clippy added a new lint detecting unnecessary borrows in expressions
where the borrowed thing is already a reference...which is nice, and
all, but the downside is that now we have to fix this.
This PR fixes it.
## Motivation
Newest versions of opentelemetry and opentelemetry-jaeger don't work
with the tracing-opentelemtry due to the latter still depending on a
0.14 version.
## Solution
Adjust dependencies and use new TraceFlags struct instead of constants
- Removes the default implementation.
- Makes tracing_core::span::Current::unknown public so that implementers
of Collect can use it if they didn't implement current_span() before.
- Copy the old default implementation to all implementers of Collect.
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
I dislike using `*` imports in my code, so I'm not using prelude modules
provided by libraries. With the way the examples in the
`tracing-subscriber` docs are currently set up, there is no hint on
where some methods are coming from. Just removing the prelude import
unfortunately doesn't lead to a solution. The compiler prefers the
prelude re-export:
```
= help: items from traits can only be used if the trait is in scope
help: the following trait is implemented but not in scope; perhaps add a `use` for it:
|
3 | use crate::tracing_subscriber::prelude::__tracing_subscriber_SubscriberExt;
|
```
## Solution
Use the traits directly in the documentation examples.
Since the compiler hints around this are currently very bad, it's good
to have a hint where methods in doc examples could come from in there,
for users who prefer not using the prelude.
## Motivation
Support the latest OpenTelemetry specification.
## Solution
Update `opentelemetry` to the latest `0.14.x` release. Despite breaking
changes upstream, no additional public API or behavioral changes are
necessary in `tracing-opentelemetry`, but simplifications in the
propagation of span information have removed the need for the current
internal `CompatSpan` and custom parent context construction.
Performance has improved by ~30% on current benchmarks.
It turns out that when using the global dispatcher, emitting tracing
events in a panic hook will capture the span in which the program
panicked. This is very handy for debugging panics! Thanks a lot to
@nate_mara for pointing this out to me on twitter --- I hadn't even
thought of it!
Since it isn't necessarily immediately obvious that this works, I
thought it would be nice to add an example.
* opentelemetry: support otel 0.13.0
Switches to `Cow<'static, str>` for otel event names and updates docs to
show simplified install methods.
Resolves#1323, resolves#1324
* Add simple vs batch comment
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
