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)]
This PR fixes all reported clippy lints. In most cases I have made the
suggested changes. In a few cases (e.g., `blacklisted_name` and
`cognitive_complexity`) I've just silenced the warning.
I can make stylistic changes or discard some of the lint fixes if
preferred.
This branch updates all the README links and badges. In particular, it:
* Changes build status badges to GitHub Actions, since we've turned off
the Azure Pipelines CI build,
* Removes Gitter links, since nobody is on Gitter these days and we
probably don't want to point new users to an empty chat room,
* Make Discord links "actually work"
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
A recent upstream change to `tokio-test` (tokio-rs/tokio#1728) removed
the `MockTask` API in favour of a more ergonomic `task::spawn` API. This
broke our tests for `tracing-futures` and `tracing-attributes` `std::future`
compatibility, which depend on `tokio-test` from Git.
## Solution
This branch updates these tests to use the new API, which *is* much
nicer. This should fix nightly CI.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Currently, most crates in `tracing` are configured to deny all compiler
warnings when compiling tests. This means that if the compiler reports
any warnings, the build will fail. This can be an issue when changes are
made locally that introduce warnings (i.e. unused code is added, imports
are no longer needed, etc) and a contributor wishes to test an
incomplete state to ensure their changes are on the right path. With
warnings denied, tests will not run if the project contains any
warnings, so contributors must either fix all warnings or disable the
deny attribute. Disabling the deny attribute when making changes locally
has become a fairly common practice, but it's error-prone: sometimes,
the deny attribute is commented out and then accidentally committed.
## Solution
This branch removes all `#![deny(warnings)]` attributes, in order to
allow code with warnings to compile and be tested locally while changes
are in progress. We already have [a CI job][1] that checks for compiler
warnings by trying to compile `tracing` with `RUSTFLAGS="-Dwarnings"`.
If we make this CI job required rather than allowing it to fail, we'll
still be able to ensure that no code with warnings is merged.
Additionally, I've updated all crates to use the same consistent list of
lints to apply in the `#![warn]` attribute. Previously, some crates
warned on more lints than others, which is not great. I've fixed all the
new warnings produced by the additional lints.
* chore: consistent warnings, don't deny locally
* fix warnings from new attributes
* remove warning that no longer exists on nightly
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Added:
- Support for destructuring in arguments to `#[instrument]`ed
functions (#397)
- Generated field for `self` parameters when `#[instrument]`ing
methods (#397)
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This pull request adds support to the `#[instrument]` macro for
destructured arguments.
## Motivation
The `#[instrument]` macro automatically adds function arguments as
fields on the `Span`. Previously, it would only do so for "plain"
`Ident` argument types, but would ignore destructured arguments.
## Solution
By recursively pattern matching each argument to find all identifiers it
creates, we can construct an authoritative list of all input names.
* attributes: extract param_names extractor
To enable the recursion needed to extract all the various
destructured parameter types.
* attributes: support destructured tuple arguments
* attributes: support destructured ref arguments
* attributes: support destructured tuple struct arguments
* attributes: support destructured struct arguments
* attributes: add crazy destructuring test
This is to test the combination of all the supported function
argument destructuring types.
* attributes: move destructuring tests to their own file
* attributes: apply cargo fmt
* attributes: add helpful comment to pattern pattern match
Since function signatures can only use irrefutable patterns,
we can be confident that no legal code will have any other
variant of `syn::Pat` than the ones we match on. However, to
prevent anyone else from going down the rabbit hole of
wondering about it, we add a helpful comment.
* attributes: support self argument as span field
Tokio is experimenting with Discord, and the Tokio discord server has
a Tracing channel. This PR adds Discord links to READMEs.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Added:
- Optional `skip` argument to `#[instrument]` for excluding function
parameters from generated spans (#359)
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
This adds a `skip` directive to the `#[instrument]` macro that allows
specifying one or more arguments to the function which will not appear
in the generated span. In particular, this means that it's possible to
use `#[instrument]` on functions with a non-`Debug` parameter.
## Solution
The interior of a `skip(arg1, arg2)` argument is scanned for identifiers
and these are filtered out of the identifier list used to generate the
span.
Closes#11.
This fixes compilation errors with `#[instrument]`ed `async fn`s on the
latest nightly. The generated `async` block was not `async move`, so the
function's attributes were not moved into it.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Fixes#298
## Solution
Add a new function to either parse the name from the macro's attribute
or return the default name (instrumented method's name). Do you want to
have the previous function's name as a field? In that case, that would
require a bit of change (maybe return an option of something from
`name`).
I added some tests, please tell me if you need more (in the nightly
async/await test for example)
refs: #298
chore: build and publish documentation for each branch.
This commit introduces support for:
- building and deploying documentation for the master branch
- building and deploying (preview) documentation for each pull request
and for each PR
- adds a link in `README.md` pointing to the generated documentation
for the master branch
- notes the per-PR documentation previews in `CONTRIBUTING.md`
Closes#210
## Motivation
Currently, most crates in this repository have `examples` directories
that contain demonstrations of how to use that crate. In many cases,
these examples also use APIs from _other_ crates in this repository ---
for example, the `tracing-subscriber` `FmtSubscriber` is used by many
examples to format the output generated by instrumentation APIs, so that
users can see the generated output.
The disadvantage to this approach is that it requires crates in this
repository to have dev-dependencies on each other. This is problematic
for a few reasons:
* It makes it easy to inadvertently create cyclic dependencies between
`tracing` crates.
* When building a crate that depends on a crate with dev-dependencies,
those dev-dependencies are downloaded and compiled, despite not being
linked into the dependent crate. This means that users depending on a
tracing crate will pull in a larger dependency tree, since the
dev-dependencies used by examples are also downloaded, although they
are not required by the dependent. This makes the tracing crate
appear to be a much larger dependency than it actually is, and can
make users' build times slower.
* Finally, it means that the examples are scattered throughout the
repository. In some cases, the examples demonstrate the functionality
of multiple crates, but only live in one crate's `examples` dir. This
can hurt the discoverability of the examples, especially for new
users.
## Solution
This branch moves all the examples out of individual crates and into a
new `examples` crate (which is otherwise empty and cannot be published
to crates.io). The `examples` crate is part of the root `tracing`
workspace, so it's still possible to `cargo run --example WHATEVER`.
Similarly, `cargo test --all` will still build the examples.
All dev-dependencies which were only required by examples and not tests
have been removed, which has a drastic impact on the dependency
footprint of some crates.
Finally, I've added a README to the `examples` crate, listing the
available examples and what functionality they demonstrate.
Refs: #315, #308
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
As discussed in #308, there are a large number of crates in this
repository, which can be confusing for users and can increase the
maintainance burden for maintainers. Also, the `tracing-fmt` and
`tracing-subscriber` crates both contain filtering implementations with
similar behaviour and APIs, but `tracing-subscriber`'s filter module
offers more advanced features (filtering on field values), and is usable
with any subscriber implementation. Two separate filter implementations
also has the potential to be confusing for users.
## Solution
This branch moves most of the code from `tracing-fmt` into a module in
`tracing-subscriber`, and changes the `tracing-fmt` builder APIs to use
the `Filter` type in `tracing-subscriber`. The `tracing-subscriber/fmt`
feature flag can be used to disable the formatting subscriber when it is
not used.
The `tracing-fmt` crate has been updated to re-export the APIs from
`tracing-subscriber`, and marked as deprecated. Once we've published a
new version of `tracing-subscriber` with the format APIs, we can publish
a final release of `tracing-fmt` that will update the documentation &
mark all APIs as deprecated, so that users know to move to the
`tracing-subscriber` crate.
Refs: #308
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
### Changed:
- Updated `syn` and `quote` dependencies to 1.0 (#292)
- Removed direct dependency on `proc-macro2` to avoid potential version
conflicts (#296)
### Fixed:
- Outdated idioms in examples (#271, #273)
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
