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
* core: remove `local_inner_macros`
This is unnecessary as we no longer support Rust 1.26
* core: prepare to release 0.1.5
Added:
- `std::error::Error` as a new primitive `Value` type (#277)
- `Event::new` and `Event::new_child_of` to manually construct `Event`s (#281)
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## 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>
## Motivation
Now that `tracing-subscriber` supports `Layer`ing subscribers, there is
a compelling use-case for constructing events without immediately
dispatching them to the default subscriber. In particular, this can be
used by a layer that aggregates or rolls up events and forwards those
aggregates to the root subscriber.
## Solution
This branch adds `new` and `new_child_of` functions to `Event`.
Fixes: #90
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This branch makes some minor tweaks to the `tracing-core` RustDoc,
including fixing some broken links, and using `#[doc(inline)]` on some
of the more important re-exports so they're highlighted front and centre
in the docs.
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>
This branch makes a few small README and Cargo.toml changes:
* Add Azure Pipelines build status badges to Cargo.tomls
* Change README build status badges to Azure Pipelines
* Add "maintenance: experimental" badges to unreleased crates
* Link to `tracing` docs and crates.io page in the root README,
rather than `tracing-core`.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
As mentioned in #189, having a `FromStr` implementation for `Level`
could be useful for various cases (the first one being level parsing for
`fmt` filters).
We will be able to use it in the filter parser once it is released, with
something like:
```rust
fn parse_level(from: &str) -> Option<LevelFilter> {
from.parse::<Level>()
.ok()
.map(LevelFilter::Level)
.or_else(|| match from {
// Handle special values that are not levels but make sense as filters
"0" | "off" => Some(LevelFilter::Off),
"" => Some(LevelFilter::Level(Level::ERROR)),
_ => None,
})
}
```
## Motivation
The `tracing-core::dispatcher` module is currently somewhat
under-documented, which has caused confusion for many users. There
should be a detailed description of how traces are dispatched, and the
different methods of setting a default subscriber. In addition, the
`tokio` feature flag that enables automatic dispatcher propagation is
undocumented, which has also caused issues (see #169).
## Solution
This branch adds new module-level docs to the `dispatcher` module,
including examples of how default subscribers are set. It also corrects
a factual error in the documentation for `with_default`.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
As discussed in [PR 149], we determined that the `Subscriber::drop_span`
method should be deprecated in favour of `try_close`. This commit
deprecates it.
[PR 149]: https://github.com/tokio-rs/tracing/pull/149#discussion_r300802298
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This commit adds implementations of `Into<Option<Id>>`,
`Into<Option<&'a Id>>`, and `Into<Option<&'static Metadata<'static>>>`.
These should make using `span::Current` with functions like
`Span::record_follows_from` in `tracing` more fluid.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
As discussed in #136, a proposed `Layer` trait for composing subscribers
required should probably _not_ be responsible for managing ref-counts
and determining span closures. Instead, the root subscriber should be
responsible for this, and `Layer`s should be able to opt into a callback
that's notified _when_ a span is closed.
Adding a callback that's called on closure to `Layer` requires modifying
the `Subscriber` trait to allow indicating when a span closes.
## Solution
This branch attempts to do this without a breaking change, by adding a
new `try_close` trait method to `Subscriber`. `try_close` is identical
to `drop_span` except that it returns a boolean value, set to `true` if
the span has closed.
The `try_close` default implementation simply calls
`self.drop_span(...)` and returns `false`, so that if subscribers don't
care about tracking ref counts, close notifications will never be
triggered.
The `drop_span` documentation now indicates that it is "soft deprecated"
similarly to `std::error::Error`'s `description` method. This encourages
subscribers to implement the new API, but isn't a breaking change.
Existing _callers_ of `drop_span` are still able to call it without
causing issues. A subsequent PR will mark `drop_span` as deprecated
in favour of `try_close`.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This branch prepares `tracing-core` to release v0.1.1, and makes a few
minor README and crates.io metadata improvements.
Changelog:
### Added
- `Subscriber::current_span` API to return the current span (#148).
- `span::Current` type, representing the `Subscriber`'s view of the current
span (#148).
### Fixed
- Typos and broken links in documentation (#123, #124, #128, #154)
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
In many cases, it is valuable to be able to get the ID and metadata of
the span that the subscriber considers to be "current". This makes
propagating the span across easier, which is vital in cases such as
`tower-buffer`.
## Solution
This branch adds a new type to `tracing-core::span` representing a
subscriber's view of the current span. This type can indicate that there
is no current span, that the subscriber does not track the current span,
or it can contain the current span's ID and metadata. A new method
`current_span` is added to the `Subscriber` trait that returns this
current span type. In order to avoid a breaking change,
`Subscriber::current_span` has a default implementation that returns a
value indicating that the current span is not tracked by the subscriber.
A new `Span::current` function is added to `tracing::Span` that uses the
`tracing-core` API to return a handle to the current span. This is the
primary way users are expected to interact with this feature.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This branch removes all remaining references to the
non-existent `tracing-nursery` repository that weren't
removed in #142 and #141.
Closes#125
* chore: remove nursery mentions from .github
* core: remove references to `tracing-nursery`
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
#122 updated all crates to use Rust 2018 syntax, but I neglected to add
`edition = "2018"` to the `Cargo.toml`s.
## Solution
This fixes that.
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This branch makes several tweaks and improvements to the `tracing` API
docs and READMEs. I've fixed some broken links in the API docs, tweaked
some wording and added more detail based on some of @jonhoo's earlier
suggestions. Additionally, I've added additional Cargo metadata and
added more links in the READMEs.
Co-Authored-By: Jon Gjengset <jon@thesquareplanet.com>
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
## Motivation
Currently, the `span::Attributes` type in `tokio-trace-core` contains a
reference to `Metadata` with a generic lifetime `'a`. This means that if
a `Subscriber` wishes to store span metadata, it cannot simply store a
`&'static Metadata<'static>`. Instead, it must extract the individual
components from the metadata and store them in its own structure. In
addition, while the `name` and `FieldSet` in a `Metadata` are always
`'static`, the target and file path are not. If the `Subscriber` needs
to store those values, they must be cloned into a `String` on the heap.
This is somewhat unergonomic for subscriber implementors, in comparison
to being able to use a `&'static Metadata<'static>` reference. In
addition, it implies additional overhead when using certain parts of a
span's metadata.
## Solution
This branch changes the `Metadata` fields in `Event` and `Attributes` to
be `'static`, and `Subscriber::register_callsite` to take an
`&'static Metadata<'static>`. Unlike PR #108, this branch leaves
`Metadata` generic over a lifetime, and `Subscriber::enabled` takes an
`&'a Metadata<'a>`.
Since subscribers are provided all span metadata as a static reference
in both `register_callsite` and `new_span`, they can clone _those_
static references, but `Subscriber::enabled` can still be called with
`Metadata` constructed from a `log::Record`. This means that log records
can still be filtered as normal. A different callsite, which does not
have metadata from the log record, is used when actually recording
events constructed from `log::Records`; in a follow-up, we can propagate
the log metadata as fields there.
Closes#78Closes#108
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>
