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/
`tracing-subscriber` has been on `0.3` for almost a year now.
I naively copied the versions from the README, and when trying to use
the library with the current versions of e.g. `tracing-opentelemetry`, I
ran into the same error message as seen in this issue:
https://github.com/tokio-rs/tracing/issues/852
Co-authored-by: Bryan Garza <1396101+bryangarza@users.noreply.github.com>
## Motivation
This PR adds [`tracing-forest`](https://crates.io/crates/tracing-forest)
to the list of related crates. `tracing-forest` provides contextual
coherence when writing logs, and is being used by projects like
[Kanidm](https://github.com/kanidm/kanidm/).
## Solution
I added it to the documentation in `lib.rs` and in the README. Am I
missing anything else?
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.
Currently, the documentation states in a few places that the
`tracing-futures` crate is required for asynchronous code to use
`tracing`. This is no longer the case, as `tracing` provides the
`Instrument` combinator for futures; `tracing-futures` is only needed
for things defined in the `futures` crate, such as `Stream` and `Sink`.
This branch updates the documentation so that it doesn't incorrectly
state that `tracing-futures` is required.
## Motivation
As a new user, I stumbled over a broken link and thought I'd fix it.
Also noticed an unrelated open issue while searching for one about the
broken link, and thought I'd fix that too.
## Solution
Fix the typos.
The test-env-log crate has been renamed to test-log to better reflect
its intent of not only catering to env_logger specific initialization
but also tracing (and potentially others in the future).
This change updates the documentation to reference test-log instead of
the now deprecated test-env-log.
## Motivation
From the readme
> (if you're the maintainer of a tracing ecosystem crate not in this list, please let us know!)
## Solution
Added links to tracing-elastic-apm.
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
This PR renames the following:
- `tracing_core::Subscriber` to `tracing_core::Collect`
- `tracing_subscriber::layer::Layer` to `tracing_subscriber::layer::Subscribe`
Authored-by: David Barsksy <dbarsky@amazon.com>
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
This will avoid breaking CI on new releases of clippy. It also makes the
code a little easier to read.
## Solution
- Convert `match val { pat => true, _ => false }` to `matches!(val, pat)`
- Remove unnecessary closures
- Convert `self: &mut Self` to `&mut self`
This bumps the MSRV to 1.42.0 for `matches!`.
The latest version of rust is 1.46.0, so as per
https://github.com/tokio-rs/tracing#supported-rust-versions this is not
considered a breaking change.
I didn't fix the following warning because the fix was not trivial/needed
a decision:
```
warning: you are deriving `Ord` but have implemented `PartialOrd` explicitly
--> tracing-subscriber/src/filter/env/field.rs:16:32
|
16 | #[derive(Debug, Eq, PartialEq, Ord)]
| ^^^
|
= note: `#[warn(clippy::derive_ord_xor_partial_ord)]` on by default
note: `PartialOrd` implemented here
--> tracing-subscriber/src/filter/env/field.rs:98:1
|
98 | / impl PartialOrd for Match {
99 | | fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
100 | | // Ordering for `Match` directives is based first on _whether_ a value
101 | | // is matched or not. This is semantically meaningful --- we would
... |
121 | | }
122 | | }
| |_^
= help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#derive_ord_xor_partial_ord
```
As a side note, this found a bug in clippy 😆https://github.com/rust-lang/rust-clippy/issues/6089
## Motivation
tracing-tracy has become tested enough that I’m comfortable with suggesting it to
people at least to try out.
## Solution
List the crate among other related crates.
Includes a listing of `diesel-tracing` as a related third party crate.
This crate provides instrumented versions of the Diesel Connection
structs that will also collect and report information about the
underlying connection.
## Motivation
`diesel-tracing` is a third party integration that provides
instrumentation for diesel connections which may be useful to some
`tracing` users.
https://github.com/CQCL/diesel-tracing/issues/7
## Solution
Adds `diesel-tracing` to the documentation so that users might discover
it.
This PR adds [`tracing-unwrap`](https://docs.rs/tracing-unwrap) to the
list of related crates in the readme.
`tracing-unwrap` provides convenience methods to unwrap `Result` and
`Option` types and automatically report failures via `tracing` before
panicking.
Feel free to edit the description I wrote as you see fit. Thanks!
The test-env-log crate comes in useful when testing tracing based
applications/libraries. With this change we mention it in the Related
Crates section of the README in the root directory and the tracing crate
itself.
## Motivation
PR #934 fixed a bug in the CI configuration where MSRV checks were not
being run correctly. After this was fixed, it was necessary to bump the
MSRV to 1.40.0, as the tests were no longer actually passing on 1.39,
because some dependencies no longer support it.
While updating the documentation to indicate that the new MSRV is 1.40,
I noticed that the note on the MSRV was located inconsistently in the
READMEs and `lib.rs` documentation of various crates, and missing
entirely in some cases. Additionally, there have been some questions on
what our MSRV _policies_ are, and whether MSRV bumps are considered
breaking changes (see e.g. #936).
## Solution
I've updated all the MSRV notes in the documentation and READMEs to
indicate that the MSRV is 1.40. I've also ensured that the MSRV note is
in the same place for every crate (at the end of the "Overview" section
in the docs), and that it's formatted consistently.
Furthermore, I added a new section to the READMEs and `lib.rs` docs
explaining the current MSRV policy in some detail. Hopefully, this
should answer questions like #936 in the future. The MSRV note in the
overview section includes a link to the section with further details.
Finally, while doing this, I noticed a couple of crates
(`tracing-journald` and `tracing-serde`) were missing top-level `lib.rs`
docs. Rather than just adding an MSRV note and nothing else, I went
ahead and fixed this using documentation from those crate's READMEs.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This puts the splash SVG in every crate's README, so
that it will be rendered on crates.io.
I also changed the link to an absolute URL, to ensure that
it works even outside of the repo.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This branch adds an SVG splash graphic to the main
repository readme, based on the illustration on tokio.rs.
I thought about sticking a big "As seen in rustc!" on there,
and we *could* still do this...
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
The documentation nearly put me off trying to use `tracing` at all. It
looks hard to set up and use, and the two problems I first ran into
(needing to output to stderr, and instrumenting a function with a
non-formattable arg) were not easy to find the right solutions for.
## Solution
This change rearranges the README a little to emphasise solutions,
rather than problems and extra details a first time user probably
doesn't need to care about yet.
* Start with the simple way of setting up a subscriber rather than
diving into the complex ways.
* Show the preferred method of instrumenting async code before
explaining why it is more complex and how it's implemented.
* Remove yak credit. Does anyone care?
* Further tweaks to README contents
Address @hawkw review comments. Opted for clearer wording in passages
joining examples together rather than extra reordering for now.
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
I spent quite a large portion of my talk at Rusty days discussing
logging/structured logging/distributed tracing, covering our usage of `tracing`.
If you think it's relevant I'd be happy to add it to the list 😁
P.S. there were some trailing whitespaces that my VIM setup ruthlessly
eliminated. Let me know if you want me to leave them there.
* Add talk
* Use uniform format
Fixed
- Missing `fmt::Display` impl for `field::DisplayValue` causing a
compilation failure when the "log" feature is enabled (#887)
Thanks to @d-e-s-o for contributing to this release!
### Added
- `LevelFilter` type and `LevelFilter::current()` for returning the
highest level that any subscriber will enable (#853)
- `Subscriber::max_level_hint` optional trait method, for setting the
value returned by `LevelFilter::current()` (#853)
### Fixed
- **docs**: Removed outdated reference to a Tokio API that no longer exists
(#857)
Thanks to new contributor @dignati for contributing to this release!
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Some opentracing systems use fields with : in the names, which are not
legal rust identifiers. We could special case :, but then we have
complicated double-nested patterns (repeated idents separated by : and a
nested repeat separated by .), and this may by a case of always being
one-step-behind as more cases turn up; so this patch instead just gets
in front and lets users put in whatever they want: as they are not rust
identifiers, they miss out on some niceness.
## Solution
This permits : in field names but also potentially anything
stringifiable, which may be overly liberal.
Signed-off-by: Robert Collins <robert.collins@cognite.com>
## Motivation
I'd like to get more feedback on our [`tracing-wasm` crate][1], as well as
improve its discoverability.
[1]: https://crates.io/crates/tracing-wasm
## Solution
Add a link to the crate to the "Related Crates" section of the readme file.
## Motivation
some of the links in the readme don't work or go to the wrong targets
## Solution
* the `closing` link needs another `tracing/` in the path
* the `#[instrument]` link apparently can't have `#[ ]`
* `tracing-core` shouldn't be another link to `tracing`
* avoid duplicate link targets for contained crates
## Motivation
From the readme
> (if you're the maintainer of a tracing ecosystem crate not in this list, please let us know!)
## Solution
Added link to tide-tracing on readme and doc comment.
## Motivation
Support for writing tracing-based logs directly to their standard
destination while preserving both standard and custom metadata on Linux
systems. Improves usability of Linux services and for Linux applications
executing outside of a terminal.
## Solution
It turns out [journald's native protocol][1] is very simple and spoken
over a Unix datagram socket at a fixed location (see [discussion of
stability of these interfaces][2], allowing high quality native support
with ~100LoC.
[journald conventions][3] for structured field names differ from typical
tracing idioms, and journald discards fields which violate its
conventions. Hence, this layer automatically sanitizes field names by
translating `.`s into `_`s, stripping leading `_`s and
non-ascii-alphanumeric characters other than `_`, and upcasing.
Levels are mapped losslessly to journald `PRIORITY` values as follows:
- `ERROR` => Error (3)
- `WARN` => Warning (4)
- `INFO` => Notice (5)
- `DEBUG` => Informational (6)
- `TRACE` => Debug (7)
Note that the naming scheme differs slightly for the latter half.
The standard journald `CODE_LINE` and `CODE_FILE` fields are
automatically emitted. A `TARGET` field is emitted containing the
event's target. Enclosing spans are numbered counting up from the root,
and their fields and metadata are included in fields prefixed by `Sn_`
where `n` is that number.
User-defined fields other than the event `message` field have a prefix
applied by default to prevent collision with standard fields.
[1]: https://www.freedesktop.org/wiki/Software/systemd/export/
[2]: https://systemd-devel.freedesktop.narkive.com/i5tlUyjz/client-logging-to-journald-without-libsystemd-journal-so#post6
[3]: https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html
This branch makes the following changes:
- Add a new section to the `Span::enter` docs that explains why
it should be avoided in async code, and suggests alternatives.
- Add links to the new section elsewhere.
- Add new formatting for "Notes" and "Warnings" in the documentation,
by (mis?)using existing styles from the RustDoc stylesheet.
- Fixed a handful of inaccuracies or outdated statements I noticed
while making other changes.
Fixes #667
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
