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>
## Motivation
As discussed in #292:
> A follow-up to remove an explicit dependency on `proc-macro2` would be
> great, though, as it would make it easier to avoid pulling duplicate
> versions of that crate.
## Solution
Remove `proc-macro2` as a direct dependency and replace usages of types
from it accordingly.
- remove `proc-macro2` as a direct dependency
- replace usage of `TokenStream` from `proc-macro2` with `impl ToTokens`
from `quote`
- remove usage of `Span::call_site` as that is used by default for the
`quote!` macro
## Motivation
`tokio` 0.2 introduced a `tokio-macros` crate that uses macro-related
dependencies similar to `tracing-attributes`. Recently, [those
dependencies were updated][1], incorporating breaking changes from those
dependencies. This means that users of `tokio` 0.2 and
`tracing-attributes` will have duplicate dependencies.
[1]: https://github.com/tokio-rs/tokio/pull/1432
## Solution
Update `proc-macro2`, `syn`, and `quote` to version 1, and react to the
breaking changes (mostly in `syn`).
Note that this is currently a naive, compiler-error-driven refactoring
of `tracing-attributes`. Everything appears to be working, but I'm not
sure if there's a better (e.g. more performant) way to use the new
dependencies. Additionally, I noticed that `tokio-macros` dropped having
a direct dependency on `proc-macro2`, and I don't know if
`tracing-attributes` should do the same.
- update `quote`, `syn`, and `proc-macro2` all to version 1
- react to breaking changes in `syn`
Fixes: #270
## Motivation
Some Tracing examples, especially in unstable crates, were written
against earlier versions of `tracing`. They don't always demonstrate
the most idiomatic use of Tracing APIs.
## Solution
This updates the examples to use newer Tracing APIs and syntax. Now, the
examples will demonstrate the preferred idioms.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
`tracing` is built with Rust's 2018 edition, but some examples use
outdated idioms. Ideally, examples would show code using the currently
preferred idioms. This improves clarity, especially for newer Rust
programmers who may not be familiar with the idioms of earlier editions.
## Solution
This branch updates all the examples to use Rust 2018 edition idioms,
and adds `deny` attributes to prevent the use of outdated idioms.
* deny rust 2018 idiom lints in examples
* examples: update to use Rust 2018 idioms
* examples: remove most uses of `extern crate`
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Users have expressed interest in using `tracing` on no_std platforms
with `liballoc`. Now that `tracing-core` supports no_std (see #256),
we can now add no_std support to `tracing` as well.
## Solution
This branch adds `no_std` support to `tracing` 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::Once` rather than `std::sync::Once`, 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).
Some tests, which rely on the thread-local dispatcher, are disabled when
the standard lib is disabled. The alternative is to use
`set_global_default` in those tests, which would necessitate placing
each test in its own separate file. Since the behavior being tested is
otherwise the same regardless of whether or not the standard library is
used, I opted to disable these tests instead.
Refs: #256Closes: #213
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
# 0.1.1 (August 9, 2019)
### Changed
- Using the `#[instrument]` attribute on `async fn`s no longer requires a
feature flag (#258)
### Fixed
- The `#[instrument]` macro now works on generic functions (#262)
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Want to be able to use the amazing `#[instrument]` attribute on
functions which have generics/bounds.
## Solution
Add these to the proc macro.
## Motivation
Currently, using `tracing-attributes` with an `async fn` requires a
feature flag, as well as being on a compiler that supports async-await.
This is an unfortunate usability speedbump that is necessary as the Rust
1.34 compiler will fail on any file _containing_ `async` or `await`,
even if they are inside a macro input (such as `quote!`).
## Solution
This branch removes the necessity of feature-flagging async-await
support by constructing `syn::Ident` instances for the "async" and
"await" keywords, rather than quoting them. This means that
`#[instrument]` will now work for `async fn`s on any compiler that
supports async-await, without requiring a feature flag.
I've left the feature flag defined, although it no longer does anything.
Removing it would be a breaking change for code that enables it.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
In order to re-export the `#[instrument]` attribute macro in `tracing`,
it must be released to crates.io. There are some changes that needed to
be made prior to releasing the procedural macro crate.
## Solution
This branch makes the following changes:
- Rename the attribute macro from `trace` to `instrument` (see #246)
- Add support for setting a verbosity level (see #250)
- Add support for setting a target
- Rename the `tracing-proc-macros` crate to `tracing-attributes`
- Add documentation + a README
- Update Cargo.toml metadata
The crate should now be ready to publish and re-export from `tracing`.
Fixes: #246Fixes: #250
Refs: #245
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
