docs: document valuable support
#1887
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This changes the `valuable` integration so that `record_value` takes
instances of `valuable::Value<'_>`, rather than `&dyn
valuable::Valuable` trait objects. The primary advantage of this is that
a `Value` can be produced by calling `Valuable::as_value`, so it allows
users to write code like this:
```rust
#[derive(Valuable, Debug)]
struct Foo {
// ...
}
tracing::trace!(foo = foo.as_value());
```
rather than this:
```rust
#[derive(Valuable, Debug)]
struct Foo {
// ...
}
tracing::trace!(foo = tracing::field::valuable(&foo));
```
which feels a bit more ergonomic. It also simplifies the code in
`tracing-core`, since we no longer need our own `ValuableValue` wrapper
type to turn things into trait objects.
It might also reduce boilerplate a bit on the visitor side, as
`as_value()` doesn't have to be called on the trait object, although
that's probably not as big a deal.
I didn't remove the `field::valuable` function, as I thought it was nice
to have for consistency with the existing `field::debug` and
`field::display` functions.
## Performance Considerations
@carllerche pointed out that a `Value<'_>` might be slightly more bytes
to pass on the stack than a trait object (always two words). I believe
this is only the case when the `Value` is a `Listable`, `Enumerable`,
`Structable`, `Mappable`, or `Tupleable`, where the `Value` would be an
enum descriminant _and_ a wide pointer to a trait object. However, in
the cases where the value is a primitive, `Value` will be two words if
the primitive is word-sized (e.g. `u64` on 64-bit platforms), for the
enum descriminant + the value, or one word if the primitive is smaller
than word size (`bool`, `char`, etc). Also, for primitive `Value`s,
there's no pointer dereference, which the trait object always requires.
I'm not sure how the enum dispatch compares to vtable dispatch when
calling `visit` on the value. However, if the `tracing` visitor is going
to call `as_value()` on the recorded value, this approach is better,
because calling `as_value()` in the macro _prior_ to recording the
span/event will use the statically dispatched `as_value()` impl on a
known type, rather than the the dynamically dispatched `as_value()` impl
on the trait object. Since `as_value` impls are generally quite trivial,
I'd guess they usually (always?) will get inlined, which is never
possible with the dynamically dispatched call after passing a trait
object into `tracing`.
In practice I'm not sure if there's a huge perf diff either way, but it
was interesting to think through the implications.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
davidbarsky
reviewed
Feb 2, 2022
Co-authored-by: David Barsky <me@davidbarsky.com>
Co-authored-by: David Barsky <me@davidbarsky.com>
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
davidbarsky
approved these changes
Feb 3, 2022
| //! represents the behavior used to record values of various types. For example, | ||
| //! an implementation of `Visit` might record integers by incrementing counters | ||
| //! for their field names rather than printing them. | ||
| //! |
There was a problem hiding this comment.
removing an extra space I just noticed.
Suggested change
| //! |
hawkw
added a commit
that referenced
this pull request
Feb 4, 2022
# 0.1.22 (February 3, 2022) This release adds *experimental* support for recording structured field values using the [`valuable`] crate. See [this blog post][post] for details on `valuable`. Note that `valuable` support currently requires `--cfg tracing_unstable`. See the documentation for details. ### Added - **field**: Experimental support for recording field values using the [`valuable`] crate ([#1608], [#1888], [#1887]) - **field**: Added `ValueSet::record` method ([#1823]) - **subscriber**: `Default` impl for `NoSubscriber` ([#1785]) - **metadata**: New `Kind::HINT` to support the `enabled!` macro in `tracing` ([#1883], [#1891]) ### Fixed - Fixed a number of documentation issues ([#1665], [#1692], [#1737]) Thanks to @xd009642, @Skepfyr, @guswynn, @Folyd, and @mbergkvist for contributing to this release!
hawkw
added a commit
that referenced
this pull request
Feb 4, 2022
# 0.1.22 (February 3, 2022) This release adds *experimental* support for recording structured field values using the [`valuable`] crate. See [this blog post][post] for details on `valuable`. Note that `valuable` support currently requires `--cfg tracing_unstable`. See the documentation for details. ### Added - **field**: Experimental support for recording field values using the [`valuable`] crate ([#1608], [#1888], [#1887]) - **field**: Added `ValueSet::record` method ([#1823]) - **subscriber**: `Default` impl for `NoSubscriber` ([#1785]) - **metadata**: New `Kind::HINT` to support the `enabled!` macro in `tracing` ([#1883], [#1891]) ### Fixed - Fixed a number of documentation issues ([#1665], [#1692], [#1737]) Thanks to @xd009642, @Skepfyr, @guswynn, @Folyd, and @mbergkvist for contributing to this release! [`valuable`]: https://crates.io/crates/valuable [post]: https://tokio.rs/blog/2021-05-valuable [#1608]: #1608 [#1888]: #1888 [#1887]: #1887 [#1823]: #1823 [#1785]: #1785 [#1883]: #1883 [#1891]: #1891 [#1665]: #1665 [#1692]: #1692 [#1737]: #1737
hawkw
added a commit
that referenced
this pull request
Feb 4, 2022
# 0.1.30 (February 3rd, 2021) This release adds *experimental* support for recording structured field values using the [`valuable`] crate. See [this blog post][post] for details on `valuable`. Note that `valuable` support currently requires `--cfg tracing_unstable`. See the documentation for details. This release also adds a new `enabled!` macro for testing if a span or event would be enabled. ### Added - **field**: Experimental support for recording field values using the [`valuable`] crate ([#1608], [#1888], [#1887]) - `enabled!` macro for testing if a span or event is enabled ([#1882]) ### Changed - `tracing-core`: updated to [0.1.22][core-0.1.22] - `tracing-attributes`: updated to [0.1.19][attributes-0.1.19] ### Fixed - **log**: Fixed "use of moved value" compiler error when the "log" feature is enabled ([#1823]) - Fixed macro hygiene issues when used in a crate that defines its own `concat!` macro ([#1842]) - A very large number of documentation fixes and improvements. Thanks to @@vlad-scherbina, @Skepfyr, @Swatinem, @guswynn, @teohhanhui, @xd009642, @tobz, @d-e-s-o@0b01, and @nickelc for contributing to this release! [`valuable`]: https://crates.io/crates/valuable [post]: https://tokio.rs/blog/2021-05-valuable [core-0.1.22]: https://github.com/tokio-rs/tracing/releases/tag/tracing-core-0.1.22 [attributes-0.1.19]: https://github.com/tokio-rs/tracing/releases/tag/tracing-attributes-0.1.19 [#1608]: #1608 [#1888]: #1888 [#1887]: #1887 [#1882]: #1882 [#1823]: #1823 [#1842]: #1842
hawkw
added a commit
that referenced
this pull request
Feb 4, 2022
# 0.1.30 (February 3rd, 2021) This release adds *experimental* support for recording structured field values using the [`valuable`] crate. See [this blog post][post] for details on `valuable`. Note that `valuable` support currently requires `--cfg tracing_unstable`. See the documentation for details. This release also adds a new `enabled!` macro for testing if a span or event would be enabled. ### Added - **field**: Experimental support for recording field values using the [`valuable`] crate ([#1608], [#1888], [#1887]) - `enabled!` macro for testing if a span or event is enabled ([#1882]) ### Changed - `tracing-core`: updated to [0.1.22][core-0.1.22] - `tracing-attributes`: updated to [0.1.19][attributes-0.1.19] ### Fixed - **log**: Fixed "use of moved value" compiler error when the "log" feature is enabled ([#1823]) - Fixed macro hygiene issues when used in a crate that defines its own `concat!` macro ([#1842]) - A very large number of documentation fixes and improvements. Thanks to @@vlad-scherbina, @Skepfyr, @Swatinem, @guswynn, @teohhanhui, @xd009642, @tobz, @d-e-s-o@0b01, and @nickelc for contributing to this release! [`valuable`]: https://crates.io/crates/valuable [post]: https://tokio.rs/blog/2021-05-valuable [core-0.1.22]: https://github.com/tokio-rs/tracing/releases/tag/tracing-core-0.1.22 [attributes-0.1.19]: https://github.com/tokio-rs/tracing/releases/tag/tracing-attributes-0.1.19 [#1608]: #1608 [#1888]: #1888 [#1887]: #1887 [#1882]: #1882 [#1823]: #1823 [#1842]: #1842
kaffarell
pushed a commit
to kaffarell/tracing
that referenced
this pull request
May 22, 2024
Depends on tokio-rs#1881 Right now, the `valuable` stuff isn't very discoverable --- enabling the feature just adds some trait impls and stuff that aren't particularly visible in the documentation. This PR adds some top-level docs on using `valuable`. In particular: - Added a section to the `tracing` and `tracing-core` lib.rs docs explaining the unstable features versioning policy and how to turn on unstable features - Added a section in the `field` module that explains how to use `valuable` to record fields. - It turns out the `tracing::field` module didn't really have docs, since it doesn't re-export the `tracing_core::field` module but re-exports its _types_ in a new module (because it adds a trait). It had a single line of docs that just said something about "structured key-value data". I fixed this by coping the docs from `tracing-core`. :/ - Enabled unstable features in the documentation on docs.rs and netlify.
kaffarell
pushed a commit
to kaffarell/tracing
that referenced
this pull request
May 22, 2024
# 0.1.22 (February 3, 2022) This release adds *experimental* support for recording structured field values using the [`valuable`] crate. See [this blog post][post] for details on `valuable`. Note that `valuable` support currently requires `--cfg tracing_unstable`. See the documentation for details. ### Added - **field**: Experimental support for recording field values using the [`valuable`] crate ([tokio-rs#1608], [tokio-rs#1888], [tokio-rs#1887]) - **field**: Added `ValueSet::record` method ([tokio-rs#1823]) - **subscriber**: `Default` impl for `NoSubscriber` ([tokio-rs#1785]) - **metadata**: New `Kind::HINT` to support the `enabled!` macro in `tracing` ([tokio-rs#1883], [tokio-rs#1891]) ### Fixed - Fixed a number of documentation issues ([tokio-rs#1665], [tokio-rs#1692], [tokio-rs#1737]) Thanks to @xd009642, @Skepfyr, @guswynn, @Folyd, and @mbergkvist for contributing to this release! [`valuable`]: https://crates.io/crates/valuable [post]: https://tokio.rs/blog/2021-05-valuable [tokio-rs#1608]: tokio-rs#1608 [tokio-rs#1888]: tokio-rs#1888 [tokio-rs#1887]: tokio-rs#1887 [tokio-rs#1823]: tokio-rs#1823 [tokio-rs#1785]: tokio-rs#1785 [tokio-rs#1883]: tokio-rs#1883 [tokio-rs#1891]: tokio-rs#1891 [tokio-rs#1665]: tokio-rs#1665 [tokio-rs#1692]: tokio-rs#1692 [tokio-rs#1737]: tokio-rs#1737
kaffarell
pushed a commit
to kaffarell/tracing
that referenced
this pull request
May 22, 2024
# 0.1.30 (February 3rd, 2021) This release adds *experimental* support for recording structured field values using the [`valuable`] crate. See [this blog post][post] for details on `valuable`. Note that `valuable` support currently requires `--cfg tracing_unstable`. See the documentation for details. This release also adds a new `enabled!` macro for testing if a span or event would be enabled. ### Added - **field**: Experimental support for recording field values using the [`valuable`] crate ([tokio-rs#1608], [tokio-rs#1888], [tokio-rs#1887]) - `enabled!` macro for testing if a span or event is enabled ([tokio-rs#1882]) ### Changed - `tracing-core`: updated to [0.1.22][core-0.1.22] - `tracing-attributes`: updated to [0.1.19][attributes-0.1.19] ### Fixed - **log**: Fixed "use of moved value" compiler error when the "log" feature is enabled ([tokio-rs#1823]) - Fixed macro hygiene issues when used in a crate that defines its own `concat!` macro ([tokio-rs#1842]) - A very large number of documentation fixes and improvements. Thanks to @@vlad-scherbina, @Skepfyr, @Swatinem, @guswynn, @teohhanhui, @xd009642, @tobz, @d-e-s-o@0b01, and @nickelc for contributing to this release! [`valuable`]: https://crates.io/crates/valuable [post]: https://tokio.rs/blog/2021-05-valuable [core-0.1.22]: https://github.com/tokio-rs/tracing/releases/tag/tracing-core-0.1.22 [attributes-0.1.19]: https://github.com/tokio-rs/tracing/releases/tag/tracing-attributes-0.1.19 [tokio-rs#1608]: tokio-rs#1608 [tokio-rs#1888]: tokio-rs#1888 [tokio-rs#1887]: tokio-rs#1887 [tokio-rs#1882]: tokio-rs#1882 [tokio-rs#1823]: tokio-rs#1823 [tokio-rs#1842]: tokio-rs#1842
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Depends on #1881
Right now, the
valuablestuff isn't very discoverable --- enabling thefeature just adds some trait impls and stuff that aren't particularly
visible in the documentation. This PR adds some top-level docs on using
valuable. In particular:tracingandtracing-corelib.rs docsexplaining the unstable features versioning policy and how to turn on
unstable features
fieldmodule that explains how to usevaluableto record fields.tracing::fieldmodule didn't really have docs,since it doesn't re-export the
tracing_core::fieldmodule butre-exports its types in a new module (because it adds a trait). It
had a single line of docs that just said something about "structured
key-value data". I fixed this by coping the docs from
tracing-core.:/