Currently, in many places, macros do not use fully qualified names for
items exported from the prelude. This means that naming collisions
(`struct Some`) or the removal of the std library prelude will cause
compilation errors.
- Identify and use fully qualified names in macros were we previously
assumed the Rust std prelude. We use `::core` rather than `::std`.
- Add
[`no_implicit_prelude`](https://doc.rust-lang.org/reference/names/preludes.html#the-no_implicit_prelude-attribute)
to `tracing/tests/macros.rs`. I'm unsure if this is giving us good
coverage - can we improve on this approach? I'm not confident I've
caught everything.
This branch adds documentation and tests noting that the `#[instrument]`
macro accepts `tracing::Level` directly. Using `tracing::Level` directly
allows for IDE autocomplete and earlier detection of typos.
The documentation for tracing-attributes was also rewritten to remove
the usage of the second-person perspective, making it more consistent
with the rest of tracing's documentation.
Co-authored-by: David Barsky <me@davidbarsky.com>
; Conflicts:
; tracing-attributes/Cargo.toml
; tracing-attributes/src/lib.rs
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
I've received a request at work to record 128-bit integers and realized
that we should probably support recording them.
## Solution
Added two methods to the `Visit` trait, `record_i128` and `record_u128`.
However, I didn't add the size conversions present for 64-bit integers,
as 128-bit integers are, at this time, more specialized.
## Motivation
Currently, it is rather difficult to record `String`s as field values,
even though `&str` is a primitive `Value` type. For example, this code
does not currently compile:
```rust
let my_string = String::from("hello world!");
tracing::debug!(my_string);
```
Instead, it is necessary to explicitly call `String::as_str` or a
similar conversion method:
```rust
let my_string = String::from("hello world!");
tracing::debug!(my_string = my_string.as_str());
```
This is unfortunate, as it makes a fairly straightforward, commomplace
task (recording a `String` as a field) unnecessarily verbose.
## Solution
This branch adds an `impl Value for String` in `tracing-core`. The impl
simply calls `String::as_str` and then calls `record_str`. Because
`Value` takes an `&self`, and there are preexisting `impl<T: Value>
Value` for `&T` and `&mut T`, the string is not consumed, and `&String`
or `&mut String`s can also be used as `Value`s.
I've also added tests validating that this actually works.
## Motivation
This PR adds two new accessor functions that are useful for creating a
structured serde implementation for tracing.
This is a sort of "distilled" version of
https://github.com/tokio-rs/tracing/pull/2113, based on the `v0.1.x`
branch.
As it is unlikely that "structured serde" will be 1:1 compatible with
the existing JSON-based `tracing-serde` (or at least - I'm not sure how
to do it in a reasonable amount of effort), these functions will allow
me to make a separate crate to hold me over until breaking formatting
changes are possible in `tracing-serde`.
CC @hawkw, as we've discussed this pretty extensively
* docs: `cargo intraconv` for more intra-doc links
... also it deleted some redundant ones, and it got some things wrong,
and it was gonna delete some of the cross-crate docs.rs links we can't
do as intra-doc links so I passed `--no-favored`.
* docs: convert https:// links to std/core/alloc to intra-doc links
Note that this adds some more broken intra doc links when building
without std support, but that was already a thing and I expect people
who build their own docs without std support can handle it.
This time I gave up on sed and used ruby.
find -name '*.rs' -exec ruby -i -p blah.rb {} +
with
$_.gsub!(%r{
https://doc\.rust-lang\.org/
(?: stable/)?
((?:core | std | alloc)(?:/\S+?)*)
/(\w+)\.(\w+)\.html}x
) {
path, kind, name = $~.captures
suffix = case kind
when 'method' then '()'
when 'macro' then '!'
else ''
end
r = [path.gsub('/', '::'), '::', name, suffix].join
STDERR.puts [path, kind, name, suffix, r].inspect
r
}
$_.gsub!(%r{
https://doc\.rust-lang\.org/
(?: stable/)?
((?: core | std | alloc)(?:/\S+?)*)
/(?:
index\.html
| $
| (?= \#)
)}x
) {
path, _ = $~.captures
r = path.gsub('/', '::')
STDERR.puts [path, r].inspect
r
}
* docs: more cross-crate intra-doc links
cargo intraconv doesn't seem to get them reliably and also plenty of
links to other crates aren't actually intra-doc because they're in
crates that don't depend (or only dev-depend, or only conditionally
depend) on those crates, so this wasn't very automated.
I tried to only convert docs.rs links to unconditional dependencies to
intra-crate links, but it's possible that some slipped through in either
direction.
This commit adds a `Value` implementation for `Box<T> where T: Value`.
This is *primarily* intended to make `Box<dyn Error + ...>` implement
`Value`, building on the `Value` impls for `dyn Error + ...` added in
#2066, but it may be useful for other boxed values as well.
Refs: #1308
## Motivation
#940, I guess. I kept running into the odd broken link in the docs and
eventually realized it's because a lot of stuff is reexported in parent
modules and so the file path based relative links couldn't possibly work
in all contexts. Looks like master already underwent this treatment but
I suspect this is easier than backporting.
## Solution
Intra-doc links seem pretty good.
I started with
```
find -name \*.rs -exec sed -i -e '
s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\w\+\.\(\w\+\)\.html@\1super::\2@;
s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\(\w\+\)/\w\+\.\(\w\+\)\.html@\1super::\2::\3@;
s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\.\./\w\+\.\(\w\+\)\.html@\1super::super::\2@;
s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\.\./\(\w\+\)/\w\+\.\(\w\+\)\.html@\1super::super::\2::\3@;
s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\(\w\+\)/index\.html@\1super::\2@;
s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./index\.html@\1super@;
s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\(\w\+\)/\?$@\1super::\2@;
s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./\w\+\.\(\w\+\)\.html@\1self::\2@;
s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./\(\w\+\)/\w\+\.\(\w\+\)\.html@\1self::\2::\3@;
s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./\(\w\+\)/index\.html@\1self::\2@;
s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./index\.html@\1self@;
s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./\(\w\+\)/\?$@\1self::\2@;
s@\(//. \[[^]]*\]:\s\+\)[:"]\?\w\+\.\(\w\+\)\.html@\1self::\2@;
s@\(//. \[[^]]*\]:\s\+\)[:"]\?\(\w\+\)/\w\+\.\(\w\+\)\.html@\1self::\2::\3@;
s@\(//. \[[^]]*\]:\s\+\)[:"]\?\(\w\+\)/index\.html@\1self::\2@;
s@\(//. \[[^]]*\]:\s\+\)[:"]\?index\.html@\1self@;
s@\(//. \[[^]]*\]:\s\+\)[:"]\?\(\w\+\)/\?$@\1self::\2@;
s@\(//. \[[^]]*\]:\s\+[A-Za-z_0-9:]\+\)#method\.\(\w\+\)@\1::\2@;
' {} +
```
and then removed redundant `self::`s when I realized you don't actually
need a `::` in the links, and fixed stuff up by hand as I ran into
errors from
```
x='--cfg docsrs --cfg tracing_unstable'; RUSTFLAGS=$x RUSTDOCFLAGS=$x cargo doc --all-features
```
I hope that's roughly how the docs are supposed to work.
I understand this is a relatively big unsolicited change in that it
touches a whole lot of files (definitely went further than I originally
intended), I'm happy to revise or split or reduce scope of this PR as
desired.
## 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 branch removes some unnecessary uses of the `format_args!`
and `write!` macros in `tracing-core`. Using `fmt::Display::fmt` and
similar rather than the macros may be slightly more efficient.
Co-authored-by: David Barsky <me@davidbarsky.com>
## Motivation
Fixes: #196, #1739
Previously, the `field` token trees would be substituted into the log
macro invocation and the `ValueSet`, potentially meaning they are
executed more than once.
## Solution
This changes the `event!` macro (and all the upstream macros like `info!`),
so that it only uses each field once when the log feature is enabled. It
does this by generating the log using the `ValueSet` meaning the token
trees are only substituted once.
* ci: add `tracing_unstable` to CI
Currently, the `valuable` support requires the `tracing_unstable` cfg to
be set. Because none of our current CI jobs set this, we aren't
currently testing that code, and have no way of even ensuring that it
compiles. This is Bad.
This PR adds a CI job to run tests with the unstable cfg enabled.
* core: fix wrong `self` types with `valuable`
This should fix the build.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Depends on #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.
In #1881, I accidentally had the `Visit` trait take a `&Value<'_>`. This
was probably wrong, since `Value` is `Copy` and should only be a couple
words, one of which might be a pointer...so it's probably better to just
pass the `pointer + enum descriminant` (or `integer + enum descriminant`)
instead of passing `pointer to (pointer + enum descriminant)`.
This probably also makes the API a little nicer.
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.
This branch adds initial support for using the [`valuable`] crate as an
opt-in `Value` type in `tracing`. `valuable` provides a mechanism for
defining custom ways to record user-implemented types, as well as
structured recording of standard library data structures such as maps,
arrays, and sets.
For more details, see the tracking issue #1570.
In `tracing` v0.2, the intent is for `valuable` to replace the existing
`tracing_core::field::Value` trait. However, in v0.1.x, `valuable`
support must be added in a backwards-compatible way, so recording types
that implement `valuable::Valueable` currently requires opting in using
a `field::valuable` wrapper function.
Since this is the first release of `valuable` and the API is still
stabilizing, we don't want to tie `tracing-core`'s stability to
`valuable`'s. Therefore, the valuable dependency is feature-flagged
*and* also requires `RUSTFLAGS="--cfg tracing_unstable"`.
[`valuable`]: https://github.com/tokio-rs/valuable
Co-authored-by: Daniel McKenna <daniel@emotech.co>
Co-authored-by: David Barsky <me@davidbarsky.com>
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Building a span with some field might be `None` is bother now.
Before:
```rust
let span = info!("example", data = Empty );
if let Some(data) = foo() {
span.record("data", &data);
}
```
After:
```rust
let span = info!("example", data = foo() );
```
Co-authored-by: DCjanus <DCjanus@dcjanus.com>
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Tracing is a really useful framework but a lack of floating point value
support for the core visitors means these get coerced unnecessarily to
strings.
## Solution
This change adds support for floating point (`f64`) visitors.
Impl `Value` for `&mut T` where `T: Value`.
#1378 improve the `tracing::instrument` macro's recording behavior: all
primitive types implementing the `Value` trait will be recorded as
fields of that type instead of `fmt::Debug`. This PR is a prerequisite
for those `&mut` function arguments to achieve that.
This backports PR #1335 from `master` to `v0.1.x`.
Clippy now warns about implementing `Into` rather than `From`, since
`From` automatically provides `Into` but `Into` does not provide `From`.
This commit fixes the direction of those conversions, placating Clippy.
Additionally, it fixes a redundant use of slice syntax that Clippy also
complained about.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
PR #769 was merged with some incorrect docs formatting due to
incorrect HTML that resulted from overzealous find-and-replace
misuse. See https://github.com/tokio-rs/tracing/pull/769#pullrequestreview-439416330
## Solution
This PR un-splodes it.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
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>
## Motivation
There are unnecessary spaces. Also, there is a point that requires space.
* chore: Remove duplicated spaces
* chore: Add space to make code consistent
## Motivation
Currently, the only way to interact with `Value`s is to record them with
a visitor. In the most common case, where typed data is not needed,
`Value`s are recorded with their `fmt::Debug` implementations — a
visitor which does not implement the `record_${TYPE}` traits will
automatically fall back to recording all primitive value types with
`Debug`. However, implementing a visitor requires a bit of boilerplate:
an entire trait implementation has to be written, and a visitor object
passed to `record`.
## Solution
This branch hopes to simplify this common case by adding a `Debug`
implementation to _all_ `dyn Value` trait objects. This is equivalent
to a visitor that only implements `record_debug`, but requiring less
boilerplate.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Right now, there is no way to indicate that a span field _currently_
has no value but that a value will be recorded later. Tracing used to
support this concept, but when we added local-variable shorthand, it was
removed from the macros, as we needed to use the previous syntax for
indicating empty fields for local variable shorthand. See #77 for
details.
This commit side-steps the problem of determining an appropriate
_syntax_ for empty fields by adding a special value _type_, called
`Empty`. Now, empty values can be indicated like
```rust
span!("my_span", foo = 5, bar = tracing::field::Empty);
```
The `Empty` type implements `Value`, but its' `record` method is a no-op
that doesn't' call any functions on the visitor. Therefore, when a field
is empty, the visitor will not see it. An empty field can then be
recorded later using `Subscriber::record` (or the corresponding `Span`
method in `tracing`).
Closes#77
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
For tracing there's no difference between a `NonZero*` or `Wrapping`
type and their underlying type. This allows such types to directly be
referenced by the tracing macros without requiring additional method
calls or boilerplate.
## Solution
Implemented `Value` for `Wrapping<T: Value>` and for all the `NonZero*`
types from `std::num`.
This required a slight refactoring of the macros generating the regular
integer impls as to reduce the amount of generated code.
Starts on #440.
This branch adds `doc_cfg` attributes to `tracing` and `tracing-core`,
when a `docsrs` cfg flag is passed to rustdoc. It also adds
docs.rs crate metadata to configure docs.rs to set that flag, and adds
it to the Netlify config as well.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Co-authored-by: Jane Lusby <jlusby42@gmail.com>
This is a follow up PR for #477 that runs clippy on CI.
* Switch from hecrj/setup-rust-action to actions-rs/toolchain
* Fix remaining clippy lints
* Switch to minimal rustup profile
* Replace warning step with clippy
* Remove #![feature(async_await)]
## Motivation
u8 had been forgotten from the list of automatically generated
implementations for the Value Trait. See bug report #389
## Solution
Added u8 to the list of automatically generated implementations for the
Value Trait.
Fixes: #389
## Motivation
Currently, errors are typically recorded using their `fmt::Display` or
`fmt::Debug` implementations. This doesn't give the subscriber much
control over how the error is recorded --- in particular, it cannot
decide whether to format the error using `Display` or `Debug`, and it
cannot access the error's `source` or downcast it to another error type.
The `std::error::Error` type is implemented by a majority of errors in
both the standard library and in most crates, so its use is fairly
widespread.
## Solution
This commit adds `dyn std::error::Error + 'static` as a new primitive
type. The `'static` bound is included so that the error can be downcast.
Closes: #222
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
* core: support `no-std` + `alloc`
Motivation
Users have expressed interest in using `tracing` on no_std platforms
with `liballoc`.
Solution
This branch adds `no_std` support to `tracing-core` by adding a `std`
feature flag (on by default) which can be disabled to use `libcore` +
`liballoc` instead of `libstd`.
When the `std` feature is disabled, `tracing-core` will use
`spin::Mutex` rather than `std::sync::Mutex`, and the thread-local
scoped dispatcher will be disabled (since it necessitates a defined OS
threading model, which may not exist on `no_std` platforms).
Refs: #213
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>
