This branch makes several tweaks and improvements to the `tracing` API
docs and READMEs. I've fixed some broken links in the API docs, tweaked
some wording and added more detail based on some of @jonhoo's earlier
suggestions. Additionally, I've added additional Cargo metadata and
added more links in the READMEs.
Co-Authored-By: Jon Gjengset <jon@thesquareplanet.com>
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Currently, the `span::Attributes` type in `tokio-trace-core` contains a
reference to `Metadata` with a generic lifetime `'a`. This means that if
a `Subscriber` wishes to store span metadata, it cannot simply store a
`&'static Metadata<'static>`. Instead, it must extract the individual
components from the metadata and store them in its own structure. In
addition, while the `name` and `FieldSet` in a `Metadata` are always
`'static`, the target and file path are not. If the `Subscriber` needs
to store those values, they must be cloned into a `String` on the heap.
This is somewhat unergonomic for subscriber implementors, in comparison
to being able to use a `&'static Metadata<'static>` reference. In
addition, it implies additional overhead when using certain parts of a
span's metadata.
## Solution
This branch changes the `Metadata` fields in `Event` and `Attributes` to
be `'static`, and `Subscriber::register_callsite` to take an
`&'static Metadata<'static>`. Unlike PR #108, this branch leaves
`Metadata` generic over a lifetime, and `Subscriber::enabled` takes an
`&'a Metadata<'a>`.
Since subscribers are provided all span metadata as a static reference
in both `register_callsite` and `new_span`, they can clone _those_
static references, but `Subscriber::enabled` can still be called with
`Metadata` constructed from a `log::Record`. This means that log records
can still be filtered as normal. A different callsite, which does not
have metadata from the log record, is used when actually recording
events constructed from `log::Records`; in a follow-up, we can propagate
the log metadata as fields there.
Closes#78Closes#108
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Since the minimum Rust version is now Rust 1.34, we can address some
long-standing TODOs that were previously not possible to address because
they required features unavailable on Rust 1.26.
## Solution
This branch adds public `const fn` constructors to
`tracing_core::Metadata` and `tracing_core::field::FieldSet`, and
changes the internal representation of `tracing_core::span::Id` to
benefit from non-zero optimization. We cannot add a `const fn`
constructor for `callsite::Identifier` at this time, since trait objects
as const fn parameters are not stable.
Metadata is still constructed using the `metadata!` macro, as it also
uses the `file!()`, `line!()`, and `module_path!()` macros, but the
`const fn` constructor means that `Metadata`'s fields need no longer be
`#[doc(hidden)] pub`.
Closes#105
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
See #95
This branch renames everything from `tokio-trace` to `tracing`.
Unlike PR #98, the nursery crates still depend on the crates.io
versions of `tokio-trace` and `tokio-trace-core`, but renamed
to `tracing`/`tracing-core` in `Cargo.toml`. We can update the
nursery crates to depend on local path dependencies in a
subsequent PR, as that will require making code changes to the
nursery crates.
This branch _also_ updates the minimum Rust version to 1.34.0,
to the shock and horror of the millions of `tracing` users still
on Rust 1.26.0. This was necessary in order to allow renaming
crates in `Cargo.toml`, and to resolve that not using the `dyn`
keyword is now a warning on nightly.
Closes#98Closes#95
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
