# 0.1.16 (September 13, 2021)
This release adds a new `#[instrument(skip_all)]` option to skip
recording *all* arguments to an instrumented function as fields.
Additionally, it adds support for recording arguments that are `tracing`
primitive types as typed values, rather than as `fmt::Debug`.
### Added
- add `skip_all` option to `#[instrument]` ([#1548])
- record primitive types as primitive values rather than as `fmt::Debug`
([#1378])
- added support for `f64`s as typed values ([#1522])
Thanks to @Folyd and @jsgf for contributing to this release!
[#1548]: https://github.com/tokio-rs/tracing/pull/1548
[#1378]: https://github.com/tokio-rs/tracing/pull/1378
[#1522]: https://github.com/tokio-rs/tracing/pull/1524
This branch fixes some minor RustDoc issues. In particular:
- The `broken_intra_doc_links` lint was renamed to
`rustdoc::broken_intra_doc_links`. This generates a warning, since the
old name was deprecated.
- `ignore` code blocks are specifically for _Rust_ code that should not
be compiled, not for other text blocks. We were using `ignore` on JSON
blocks, which generates a warning.
- A bunch of links in `tracing-subscriber`'s RustDocs were broken. This
fixes that.
I also changed the Netlify configuration to run with `-D warnings`, so that
we can surface RustDoc warnings in CI builds.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
The default behavior of `tracing::instrument` attribution will record
all of the function arguments as `fmt::Debug`, which is overwhelmed and
unnecessary for those primitive types, such as `bool`, `u8`, `i8`,
`u16`, `i16`, `u32`, `i32`, `u64`, `i64`, `usize`, and `isize`. Another
concerning reason is that we‘ll lose the type info of those primitive
types when record by a `Visitor`, while those type infos is essential to
some people. For example, I need to show my spans in Jaeger UI.
Make the `tracing::instrument` records other function arguments as
`fmt::Debug ` while not for those primitive types.
However, I'm not good at naming. Maybe the `RecordType` enum and its
variant aren't a good name? I'd love to seek suggestions. Thanks.
This branch fixes some annoying new clippy lints no one cares about.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
# Conflicts:
# tracing-subscriber/src/layer.rs
# 0.1.15 (March 12, 2021)
### Fixed
- `#[instrument]` on functions returning `Box::pin`ned futures incorrectly
skipping function bodies prior to returning a future ([#1297])
Thanks to @nightmared for contributing to this release!
[#1297]: https://github.com/tokio-rs/tracing/pull/1297
This backports #1297 from `master`.
Fixes#1296.
I had forgotten to use all the input statements in #1228, so we would
delete nearly all the statement of sync functions that return a boxed
future :/
This backports #1228 from `master` to `v0.1.x`.
It works with both the old and new version of async-trait (except for
one doc test that failed previously, and that works with the new
version). One nice thing is that the code is simpler (e.g.g no self
renaming to _self, which will enable some simplifications in the
future).
A minor nitpick is that I disliked the deeply nested pattern matching in
get_async_trait_kind (previously: get_async_trait_function), so I
"flattened" that a bit.
Fixes #1219.
Co-authored-by: Simon THOBY <git@nightmared.fr>
The `instrument` macro does not explain the syntax that can be used and
the main tracing docs only say that this syntax is valid for `span` and
`event` macros.
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
This backports PR #1233 to v0.1.x. This isn't *just* a simple cherry-pick
because the new tests in that branch use the v0.2.x module names, so
that had to be fixed. Otherwise, though, it's the same change, and I'll go
ahead and merge it when CI passes, since it was approved on `master`.
## Motivation
Currently, using `#[instrument(err)]` on a function returning a `Result`
with an `impl Trait` in it results in a compiler error. This is because
we generate a type annotation on the closure in the function body that
contains the user function's actual body, and `impl Trait` isn't allowed
on types in local bindings, only on function parameters and return
types.
## Solution
This branch fixes the issue by simply removing the return type
annotation from the closure. I've also added tests that break on master
for functions returning `impl Trait`, both with and without the `err`
argument.
Fixes#1227
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Motivation
----------
The closure generated by `#[instrument(err)]` for non-async functions is
not mutable, preventing any captured variables from being mutated. If a
function has any mutable parameters that are modified within the
function, adding the `#[instrument(err)]` attribute will result in a
compiler error.
Solution
--------
This change makes it so the closure is executed directly as a temporary
variable instead of storing it in a named variable prior to its use,
avoiding the need to explicitly declare it as mutable altogether or to
add an `#[allow(unused_mut)]` annotation on the closure declaration to
silence lint warnings for closures that do not need to be mutable.
The `tracing-attributes` documentation for `instrument` is out of date
and could use some improvement. In particular, it doesn't mention that
empty fields can be created in `instrument`'s `fields` argument, and
states that dotted fields are forbidden and that field values must be
literals, both of which are no longer the case. See also #1210 and
#1211.
This branch updates the docs to correct the false statements, and also
fleshes out the usage examples a bit.
I wasn't sure what to do with the old examples --- some of them are now
redundant, but it's also useful to have a big list of examples for every
allowed form. Any thoughts?
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This backports PR #991 to v0.1.x. This is primarily necessary for the MSRV
bump, since some dependencies no longer compile on Rust 1.40.0.
This has already been approved on `master`, in PR #991, so it should be
fine to ship.
## 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
In order to get a compiler warning (or error) when links are broken.
Closes#940
## Solution
- [x] add `deny(broken_intra_doc_links)`
- [x] add a note to the CONTRIBUTING.md documentation on building docs locally
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
Co-authored-by: Joshua Nelson <joshua@yottadb.com>
Instrument removes the visibility of function that looks like its
from async-trait even if its not inside a trait impl block. This
adds it back for support of proc-macros based off async-trait.
Fixes: #976
This changes the logo to a wordmark. This should be consistent
with the ones for all the other Tokio crates, when we add them
elsewhere.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
### Fixed
- Corrected wrong minimum supported Rust version note in docs (#941)
- Removed unused `syn` features (#928)
Thanks to new contributor @jhpratt for contributing to this release!
## 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>
PR #875 added code to `tracing-attributes` that uses `Option::flatten`,
which was only added to the standard library in Rust 1.40. This broke
our MSRV, but we missed it because the MSRV CI checks weren't working
correctly (fixed in #934).
This commit removes the use of `Option::flatten`, and replaces it with a
manual implementation. It's a little less pretty, but it builds on our
MSRV (1.39.0).
This PR removes the "derive" feature, which is not used.
The "extra-traits" flag could be eliminated, but at the cost of
removing `Debug` implementations for a few structs.
### Added
- Support for using `self` in field expressions when instrumenting
`async-trait` functions (#875)
- Several documentation improvements (#832, #897, #911, #913)
Thanks to @anton-dutov and @nightmared for contributing to this release!
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>
## Motivation
Not found in documentation how to change generated span name name, only in
sources, then i found issue #725
## Solution
Documentation added
## Motivation
The MIT license states:
> The above copyright notice and this permission notice
> shall be included in all copies or substantial portions
> of the Software.
## Solution
Therefore the LICENSE files should be present in each crate directory,
so they are included with `cargo publish`.
Now that the new https://tokio.rs is live, we can add the new Tracing
logo to the RustDoc!
I also added a couple missing `html_root_url` attributes in published
crates.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
# 0.1.9 (July 8, 2020)
### Added
- Support for arbitrary expressions as fields in `#[instrument]` (#672)
### Changed
- `#[instrument]` now emits a compiler warning when ignoring
unrecognized input (#672, #786)
Fixes#785
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
In PR #672, the `#[instrument]` attribute was rewritten to use a custom
`syn` parser rather than using `syn::AttributeArgs`. This was primarily
to allow the use of arbitrary expressions as fields, but it had the side
benefit of also allowing more sophisticated error reporting. In
particular, we were able to replace the previous behavior of silently
ignoring unknown input with a compiler error, which has been requested a
few times (see #772 and #727). However, emitting a compiler error for
inputs that we previously allowed (even if they did nothing) is
technically a breaking change --- see
https://github.com/tokio-rs/tracing/pull/773#issuecomment-652052525 and
following comments. This means that the other new features added in #672
cannot be released until we release `tracing-subscriber` 0.2.
## Solution
This branch avoids the breaking change by downgrading these errors to
warnings. However, it isn't currently possible to emit a warning from a
proc-macro on stable --- the `proc_macro::Diagnostic` API which would
allow this requires a nightly feature. This branch hacks around this by
generating a fake deprecated item with for each unrecognized token in
the input, emitting the skipped item's parse error as the deprecation's
`note`, and "using" the deprecated item.
The deprecated warning is used here rather than other code that will
emit compiler warnings, because it gives us a way to customize the
warning output (via the `note` field). I've tried to make it fairly
obvious that this is not a "real" deprecation. Sample output looks like
this:
Fixes#727Fixes#772
Signed-off-by: Eliza Weisman <eliza@elizas.website>
## Motivation
Fields on spans generated by `#[instrument]` consist of the parameters
to the `instrument`ed function, and a list of optional fields with
literal values passed in the `fields` argument of the attribute. The
current API for additional user-defined fields is pretty limited, since
it only accepts literals (and doesn't accept dotted field names). It
would be nice to have an API for including additional fields with values
set by calling methods on `self` or on parameters, or by accessing
values from parameters.
## Solution
This branch extends the currently supported `fields` argument to allow
providing arbitrary expressions which are invoked within the function's
scope. This is a superset of the previous support for literal values
only. In addition, field names passed to `fields` may now contain dotted
Rust identifiers.
Implementing this required rewriting how arguments to the
`#[instrument]` attribute are parsed. Previously, we used `syn`'s
`AttributeArgs` type, which parses a comma-separated of "nested meta"
items, consisting of `$ident($nested meta)`, `$ident = $nested_meta`,
paths, and literals. By replacing the use of `AttributeArgs` with our
own types implementing `syn::parse::Parse`, we can accept more
expressions in the attribute arguments position. This also lets us
reject more invalid inputs at parse-time, which improves syntax error
reporting a bit.
One thing that's worth noting is that the current implementation will
generate an _empty_ field when a field name is provided without an `=`
and a value. This makes sense when only simple fields with literal
values are permitted. However, if we accept arbitrary expressions in the
macro, this is not the ideal behavior --- we would prefer to use the
same local variable shorthand as the function-like `tracing` macros.
However, changing this now is a breaking change. Any code which uses a
name that doesn't exist in the current scope to declare an empty field
would fail to compile, because it attempts to reference a name that
doesn't exist. Instead, I left a comment noting that this is not the
ideal behavior and it should be changed next time we're ready to break
the proc macros.
Fixes: #650
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
0.1.8 (May 13, 2020)
Added:
- Support for using `#[instrument]` on methods that are part of
[`async-trait`] trait implementations (#711)
- Optional `#[instrument(err)]` argument to automatically emit an event
if an instrumented function returns `Err` (#637)
Thanks to @ilana and @nightmared for contributing to this release!
[`async-trait`]: https://crates.io/crates/async-trait
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
As outlined in #399, right now `tracing-futures` (or more precisely, the
code generated by `#[instrument]`) is not working well with async-trait.
What happens is that async-trait rewrites the trait method as a
non-async function, insides of which it pins the async method we want to
instrument, and we end up instrumenting the wrapper instead of the async
fn.
This will allow people to use traits with (seemingly) async functions
along with `#[instrument]`.
## Solution
I decided to follow the discussion at
https://github.com/dtolnay/async-trait/issues/45 and see if I could make
it working. Right now I would describe its state as "works for me, and
*should* work for everyone".
The `instrument` macro will now:
* Rewrite the block when it looks like there is async_trait involved to
wrap the internal async function instead of the wrapper generated by
`async-trait`
* Rewrite '_self' as 'self' when using #[instrument] jointly with
`async-trait`
Fixes#399
## Motivation
Currently, `tracing` uses GitHub Actions for CI. However, we have
previously used both Travis and Azure Pipelines CI. Some artifacts of
previous CI configurations, such as badges and config files, still exist
in the repo. This can be confusing, since some of these CI
configurations imply things that aren't currently true (such as old MSRV
versions).
## Solution
This branch removes the following:
- Azure Pipelines badges from cargo metadata. These currently show up
as "never built" on crates.io, since the Azure build is turned off. So, we
should just remove them.
- `.travis.yml`. We don't use Travis and there's no sense keeping around
an old config file.
- `azure-pipelines.yml`. Similarly, we no longer need this.
Fixes: #669
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
* attributes: instrument Err
This adds `#[instrument(err)]`, which will emit an error-level trace
event if the caller returns an `Err`.
Fixes#545.
* attributes: use field instead of format args
* attributes: note `err` needs Display impl
## Motivation
Currently, `tracing-futures` and `tracing-attributes` both have separate
crates for tests that require `std::future` and async/await syntax.
These date back to before these features were stable, and the tests were
separated because they could only be run on nighly Rust. This has not
been the case for a long while, and `tracing` now supports `std::future`
as the default, requiring opt-in support for `futures` 0.1. I think we
had forgotten to remove the special-cased tests when we made that
transition.
## Solution
This branch removes the special-cased test crates, and moves all
`std::future` and async/await tests into the main test dirs for these
crates. I've also removed the separate CI steps that ran these.
This should simplify things significantly!
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Previously, some compile errors generated by `tracing-attributes` on bad
inputs, such as for an invalid `skip` arg, would be generated as the
_entire_ output of the attribute. Since the attribute is invoked in item
position (to generate a function), this would result in invalid code,
and the compiler would emit a much more cryptic parse error rather than
the intended helpful error.
For example, this code
```rust
#[instrument(skip(baz))]
fn bad_skip(foo: usize) {}
```
would result in the compiler outputting this error:
```
error: macros that expand to items must be delimited with braces or followed by a semicolon
--> tracing-attributes/tests/bad_skip.rs:3:19
|
3 | #[instrument(skip(baz))]
| ^^^
|
help: change the delimiters to curly braces
|
3 | #[instrument(skip( {a}))]
| ^ ^
help: add a semicolon
|
3 | #[instrument(skip(baz;))]
| ^
```
which doesn't make a lot of sense.
## Solution
This branch changes the `instrument` attribute so that a function
definition is always generated, and any compile errors due to bad input
are generated _inside_ that function definition. This means that the
compiler won't complain at us for generating a bad function definition
before it sees our `compile_error` macros.
For example, the code I showed above now results in this error:
```
error: attempting to skip non-existent parameter
--> tracing-attributes/tests/bad_skip.rs:3:19
|
3 | #[instrument(skip(baz))]
|
```
Fixes#612
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
### Added
- Support for adding arbitrary literal fields to spans generated by
`#[instrument]` (#569)
- `#[instrument]` now emits a helpful compiler error when attempting to
skip a function parameter (#600)
Thanks to @Kobzol for contributing to this release!
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This PR adds support for adding arbitrary key/value pairs to be used as
fields to `tracing::instrument`.
Current syntax:
```rust
#[instrument(fields(key = "value", v = 1, b = true, empty))]
```
- Empty keys are supported
- If a key is not a single identifier, it's value is not a
string/int/bool (or missing), is repeated or shares a name with a
parameter, an error is reported
Fixes: #573
## Motivation
Intra-workspace dependencies can go out of sync if only referencing
crates.io, where changing one crate locally and testing the whole
library will result in errors stemming from two different versions of
the same trait etc. This is hard to keep track of and makes development
more difficult than it needs to be.
## Solution
Afaik it's common practice to specify both a version and a path as per
[the cargo docs][1]. This is what tokio does with its subcrates too.
[1]: https://github.com/rust-lang/cargo/blob/master/src/doc/src/reference/specifying-dependencies.md#multiple-locations.
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)]
