mirror of
https://github.com/tokio-rs/tracing.git
synced 2025-09-30 14:30:42 +00:00
tracing-futures: prepare to release 0.1.0 (#376)
This branch prepares for an initial stable release of `tracing-futures`. I've done some pre-release cleanup and docs work as well as updating versions. * futures: improve docs * futures: pre-release cleanup * futures: update futures-preview version * futures: nicer readme/lib docs * fix breaky path dep * also fix examples path dep Signed-off-by: Eliza Weisman <eliza@buoyant.io>
This commit is contained in:
Eliza Weisman
GitHub
parent
be8381908b
commit
87c075e349
@ -11,7 +11,7 @@ tracing = "0.1"
|
||||
tracing-core = "0.1"
|
||||
tracing-tower = { version = "0.1.0", path = "../tracing-tower" }
|
||||
tracing-subscriber = { version = "0.1", path = "../tracing-subscriber" }
|
||||
tracing-futures = { version = "0.0.1-alpha.1", path = "../tracing-futures" }
|
||||
tracing-futures = { version = "0.1.0", path = "../tracing-futures" }
|
||||
tracing-attributes = "0.1.2"
|
||||
tracing-log = { path = "../tracing-log", version = "0.1.1", features = ["env_logger"] }
|
||||
tracing-serde = { path = "../tracing-serde" }
|
||||
|
||||
3
tracing-futures/CHANGELOG.md
Normal file
3
tracing-futures/CHANGELOG.md
Normal file
@ -0,0 +1,3 @@
|
||||
# 0.1.0 (Oct 8, 2019)
|
||||
|
||||
- Initial release
|
||||
@ -1,10 +1,10 @@
|
||||
[package]
|
||||
name = "tracing-futures"
|
||||
version = "0.0.1-alpha.2"
|
||||
version = "0.1.0"
|
||||
authors = ["Eliza Weisman <eliza@buoyant.io>", "Tokio Contributors <team@tokio.rs>"]
|
||||
edition = "2018"
|
||||
repository = "https://github.com/tokio-rs/tracing"
|
||||
documentation = "https://docs.rs/tracing-futures/0.0.1-alpha.1/tracing_futures"
|
||||
documentation = "https://docs.rs/tracing-futures/0.1.0/tracing_futures"
|
||||
readme = "README.md"
|
||||
homepage = "https://tokio.rs"
|
||||
description = """
|
||||
@ -15,7 +15,7 @@ categories = [
|
||||
"development-tools::profiling",
|
||||
"asynchronous",
|
||||
]
|
||||
keywords = ["logging", "tracing", "futures"]
|
||||
keywords = ["logging", "profiling", "tracing", "futures", "async"]
|
||||
license = "MIT"
|
||||
|
||||
[features]
|
||||
@ -27,8 +27,8 @@ tokio-alpha = ["std-future", "tokio_02"]
|
||||
|
||||
[dependencies]
|
||||
futures = { version = "0.1", optional = true }
|
||||
futures-core-preview = { version = "0.3.0-alpha.18", optional = true }
|
||||
pin-project = { version = "0.4", optional = true}
|
||||
futures-core-preview = { version = "0.3.0-alpha.19", optional = true }
|
||||
pin-project = { version = "0.4", optional = true }
|
||||
tracing = "0.1"
|
||||
tokio-executor = { version = "0.1", optional = true }
|
||||
tokio = { version = "0.1", optional = true }
|
||||
@ -39,4 +39,4 @@ tokio = "0.1.22"
|
||||
|
||||
[badges]
|
||||
azure-devops = { project = "tracing/tracing", pipeline = "tokio-rs.tracing", build = "1" }
|
||||
maintenance = { status = "experimental" }
|
||||
maintenance = { status = "actively-developed" }
|
||||
|
||||
@ -1,7 +1,5 @@
|
||||
# tracing-futures
|
||||
|
||||
**Warning: Until `tracing-futures` has a 0.1.0 release on crates.io, please treat every release as potentially breaking.**
|
||||
|
||||
Utilities for instrumenting futures-based code with [`tracing`].
|
||||
|
||||
[![Crates.io][crates-badge]][crates-url]
|
||||
@ -9,27 +7,45 @@ Utilities for instrumenting futures-based code with [`tracing`].
|
||||
[![Documentation (master)][docs-master-badge]][docs-master-url]
|
||||
[![MIT licensed][mit-badge]][mit-url]
|
||||
[![Build Status][azure-badge]][azure-url]
|
||||
[![Gitter chat][gitter-badge]][gitter-url]
|
||||
[![Discord chat][discord-badge]][discord-url]
|
||||
![maintenance status][maint-badge]
|
||||
|
||||
[Documentation][docs-url] |
|
||||
[Chat (gitter)][gitter-url] | [Chat (discord)][discord-url]
|
||||
[Documentation][docs-url] | [Chat][discord-url]
|
||||
|
||||
[`tracing`]: https://github.com/tokio-rs/tracing/tree/master/tracing
|
||||
[crates-badge]: https://img.shields.io/crates/v/tracing-futures.svg
|
||||
[crates-url]: https://crates.io/crates/tracing-futures
|
||||
[crates-url]: https://crates.io/crates/tracing-futures/0.1.0
|
||||
[docs-badge]: https://docs.rs/tracing-futures/badge.svg
|
||||
[docs-url]: https://docs.rs/tracing-futures
|
||||
[docs-url]: https://docs.rs/tracing-futures/0.1.0/tracing_futures
|
||||
[docs-master-badge]: https://img.shields.io/badge/docs-master-blue
|
||||
[docs-master-url]: https://tracing-rs.netlify.com/tracing_futures
|
||||
[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg
|
||||
[mit-url]: LICENSE
|
||||
[azure-badge]: https://dev.azure.com/tracing/tracing/_apis/build/status/tokio-rs.tracing?branchName=master
|
||||
[azure-url]: https://dev.azure.com/tracing/tracing/_build/latest?definitionId=1&branchName=master
|
||||
[gitter-badge]: https://img.shields.io/gitter/room/tokio-rs/tracing.svg
|
||||
[gitter-url]: https://gitter.im/tokio-rs/tracing
|
||||
[discord-badge]: https://img.shields.io/discord/500028886025895936?logo=discord&label=discord&logoColor=white
|
||||
[discord-url]: https://discordapp.com/invite/XdPzyTZ
|
||||
[maint-badge]: https://img.shields.io/badge/maintenance-actively--developed-brightgreen.svg
|
||||
|
||||
## Overview
|
||||
|
||||
[`tracing`] is a framework for instrumenting Rust programs to collect
|
||||
structured, event-based diagnostic information. This crate provides utilities
|
||||
for using `tracing` to instrument asynchronous code written using futures and
|
||||
async/await.
|
||||
|
||||
The crate provides the following traits:
|
||||
|
||||
* [`Instrument`] allows a `tracing` [span] to be attached to a future, sink,
|
||||
stream, or executor.
|
||||
|
||||
* [`WithSubscriber`] allows a `tracing` [`Subscriber`] to be attached to a
|
||||
future, sink, stream, or executor.
|
||||
|
||||
[`Instrument`]: https://docs.rs/tracing-futures/0.1.0/tracing_futures/trait.Instrument.html
|
||||
[`WithSubscriber`]: https://docs.rs/tracing-futures/0.1.0/tracing_futures/trait.WithSubscriber.html
|
||||
[span]: https://docs.rs/tracing/0.1.9/tracing/span/index.html
|
||||
[`Subscriber`]: https://docs.rs/tracing/0.1.9/tracing/subscriber/index.html
|
||||
[`tracing`]: https://crates.io/tracing
|
||||
|
||||
## License
|
||||
|
||||
|
||||
@ -37,6 +37,7 @@ where
|
||||
}
|
||||
|
||||
#[cfg(feature = "tokio")]
|
||||
#[allow(unreachable_pub)] // https://github.com/rust-lang/rust/issues/57411
|
||||
pub use self::tokio::*;
|
||||
|
||||
#[cfg(feature = "tokio")]
|
||||
|
||||
@ -21,8 +21,6 @@ where
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// #![feature(async_await)]
|
||||
///
|
||||
/// use tokio_executor::Executor;
|
||||
///
|
||||
/// # fn docs(my_executor: &mut dyn Executor) {
|
||||
@ -57,8 +55,6 @@ where
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// #![feature(async_await)]
|
||||
///
|
||||
/// use tokio_executor::Executor;
|
||||
///
|
||||
/// # fn docs(my_executor: &mut dyn Executor) {
|
||||
@ -95,8 +91,6 @@ where
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// #![feature(async_await)]
|
||||
///
|
||||
/// use tokio_executor::Executor;
|
||||
///
|
||||
/// # fn docs(my_executor: &mut dyn Executor) {
|
||||
@ -131,8 +125,6 @@ where
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// #![feature(async_await)]
|
||||
///
|
||||
/// use tokio_executor::Executor;
|
||||
///
|
||||
/// # fn docs(my_executor: &mut dyn Executor) {
|
||||
|
||||
@ -1,8 +1,19 @@
|
||||
//! Futures compatibility for [`tracing`].
|
||||
//!
|
||||
//! `tracing` is a framework for instrumenting Rust programs to collect
|
||||
//! structured, event-based diagnostic information. This library provides
|
||||
//! utilities for instrumenting asynchronous code that uses futures.
|
||||
//! # Overview
|
||||
//!
|
||||
//! [`tracing`] is a framework for instrumenting Rust programs to collect
|
||||
//! structured, event-based diagnostic information. This crate provides utilities
|
||||
//! for using `tracing` to instrument asynchronous code written using futures and
|
||||
//! async/await.
|
||||
//!
|
||||
//! The crate provides the following traits:
|
||||
//!
|
||||
//! * [`Instrument`] allows a `tracing` [span] to be attached to a future, sink,
|
||||
//! stream, or executor.
|
||||
//!
|
||||
//! * [`WithSubscriber`] allows a `tracing` [`Subscriber`] to be attached to a
|
||||
//! future, sink, stream, or executor.
|
||||
//!
|
||||
//! # Feature flags
|
||||
//!
|
||||
@ -30,15 +41,18 @@
|
||||
//! The `tokio` and `futures-01` features are enabled by default.
|
||||
//!
|
||||
//! [`tracing`]: https://crates.io/crates/tracing
|
||||
//! [span]: https://docs.rs/tracing/0.1.9/tracing/span/index.html
|
||||
//! [`Subscriber`]: https://docs.rs/tracing/0.1.9/tracing/subscriber/index.html
|
||||
//! [`Instrument`]: trait.Instrument.html
|
||||
//! [`WithSubscriber`]: trait.WithSubscriber.html
|
||||
//! [`futures`]: https://crates.io/crates/futures
|
||||
#[cfg(feature = "futures-01")]
|
||||
extern crate futures;
|
||||
#[cfg(feature = "tokio-executor")]
|
||||
extern crate tokio_executor;
|
||||
#[cfg_attr(test, macro_use)]
|
||||
extern crate tracing;
|
||||
#![doc(html_root_url = "https://docs.rs/tracing-futures/0.1.0")]
|
||||
#![warn(
|
||||
missing_debug_implementations,
|
||||
missing_docs,
|
||||
rust_2018_idioms,
|
||||
unreachable_pub
|
||||
)]
|
||||
|
||||
#[cfg(feature = "std-future")]
|
||||
use pin_project::pin_project;
|
||||
@ -50,19 +64,78 @@ use futures::{Sink, StartSend, Stream};
|
||||
use tracing::dispatcher;
|
||||
use tracing::{Dispatch, Span};
|
||||
|
||||
/// Implementations for `Instrument`ed future executors.
|
||||
pub mod executor;
|
||||
|
||||
/// Extension trait allowing futures, streams, and skins to be instrumented with
|
||||
/// a `tracing` `Span`.
|
||||
/// Extension trait allowing futures, streams, sinks, and executors to be
|
||||
/// instrumented with a `tracing` [span].
|
||||
///
|
||||
/// [span]: https://docs.rs/tracing/0.1.9/tracing/span/index.html
|
||||
pub trait Instrument: Sized {
|
||||
/// Instruments this type with the provided `Span`, returning an
|
||||
/// `Instrumented` wrapper.
|
||||
///
|
||||
/// When the wrapped future, stream, or sink is polled, the attached `Span`
|
||||
/// will be entered for the duration of the poll.
|
||||
/// If the instrumented type is a future, stream, or sink, the attached `Span`
|
||||
/// will be [entered] every time it is polled. If the instrumented type
|
||||
/// is a future executor, every future spawned on that executor will be
|
||||
/// instrumented by the attached `Span`.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// Instrumenting a future:
|
||||
///
|
||||
// TODO: ignored until async-await is stable...
|
||||
/// ```rust,ignore
|
||||
/// use tracing_futures::Instrument;
|
||||
///
|
||||
/// # async fn doc() {
|
||||
/// let my_future = async {
|
||||
/// // ...
|
||||
/// };
|
||||
///
|
||||
/// my_future
|
||||
/// .instrument(tracing::info_span!("my_future"))
|
||||
/// .await
|
||||
/// # }
|
||||
/// ```
|
||||
///
|
||||
/// [entered]: https://docs.rs/tracing/0.1.9/tracing/span/struct.Span.html#method.enter
|
||||
fn instrument(self, span: Span) -> Instrumented<Self> {
|
||||
Instrumented { inner: self, span }
|
||||
}
|
||||
|
||||
/// Instruments this type with the [current] `Span`, returning an
|
||||
/// `Instrumented` wrapper.
|
||||
///
|
||||
/// If the instrumented type is a future, stream, or sink, the attached `Span`
|
||||
/// will be [entered] every time it is polled. If the instrumented type
|
||||
/// is a future executor, every future spawned on that executor will be
|
||||
/// instrumented by the attached `Span`.
|
||||
///
|
||||
/// This can be used to propagate the current span when spawning a new future.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
// TODO: ignored until async-await is stable...
|
||||
/// ```rust,ignore
|
||||
/// use tracing_futures::Instrument;
|
||||
///
|
||||
/// # async fn doc() {
|
||||
/// let span = tracing::info_span!("my_span");
|
||||
/// let _enter = span.enter();
|
||||
///
|
||||
/// // ...
|
||||
///
|
||||
/// let future = async {
|
||||
/// tracing::debug!("this event will occur inside `my_span`");
|
||||
/// // ...
|
||||
/// };
|
||||
/// tokio::spawn(future.in_current_span());
|
||||
/// # }
|
||||
/// ```
|
||||
///
|
||||
/// [current]: https://docs.rs/tracing/0.1.9/tracing/span/struct.Span.html#method.current
|
||||
/// [entered]: https://docs.rs/tracing/0.1.9/tracing/span/struct.Span.html#method.enter
|
||||
#[inline]
|
||||
fn in_current_span(self) -> Instrumented<Self> {
|
||||
self.instrument(Span::current())
|
||||
@ -70,15 +143,20 @@ pub trait Instrument: Sized {
|
||||
}
|
||||
|
||||
/// Extension trait allowing futures, streams, and skins to be instrumented with
|
||||
/// a `tracing` `Subscriber`.
|
||||
/// a `tracing` [`Subscriber`].
|
||||
///
|
||||
/// [`Subscriber`]: https://docs.rs/tracing/0.1.9/tracing/subscriber/trait.Subscriber.html
|
||||
pub trait WithSubscriber: Sized {
|
||||
/// Attaches the provided subscriber to this type, returning a
|
||||
/// Attaches the provided [`Subscriber`] to this type, returning a
|
||||
/// `WithDispatch` wrapper.
|
||||
///
|
||||
/// When the wrapped type is a future, stream, or sink is polled, the attached
|
||||
/// subscriber will be set as the default for the duration of that poll.
|
||||
/// When the wrapped type is a future, stream, or sink, the attached
|
||||
/// subscriber will be set as the [default] while it is being polled.
|
||||
/// When the wrapped type is an executor, the subscriber will be set as the
|
||||
/// default for any futures spawned on that executor.
|
||||
///
|
||||
/// [`Subscriber`]: https://docs.rs/tracing/0.1.9/tracing/subscriber/trait.Subscriber.html
|
||||
/// [default]: https://docs.rs/tracing/0.1.9/tracing/dispatcher/index.html#setting-the-default-subscriber
|
||||
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
|
||||
where
|
||||
S: Into<Dispatch>,
|
||||
@ -88,6 +166,20 @@ pub trait WithSubscriber: Sized {
|
||||
dispatch: subscriber.into(),
|
||||
}
|
||||
}
|
||||
|
||||
/// Attaches the current [default] [`Subscriber`] to this type, returning a
|
||||
/// `WithDispatch` wrapper.
|
||||
///
|
||||
/// When the wrapped type is a future, stream, or sink, the attached
|
||||
/// subscriber will be set as the [default] while it is being polled.
|
||||
/// When the wrapped type is an executor, the subscriber will be set as the
|
||||
/// default for any futures spawned on that executor.
|
||||
///
|
||||
/// This can be used to propagate the current dispatcher context when
|
||||
/// spawning a new future.
|
||||
///
|
||||
/// [`Subscriber`]: https://docs.rs/tracing/0.1.9/tracing/subscriber/trait.Subscriber.html
|
||||
/// [default]: https://docs.rs/tracing/0.1.9/tracing/dispatcher/index.html#setting-the-default-subscriber
|
||||
#[inline]
|
||||
fn with_current_subscriber(self) -> WithDispatch<Self> {
|
||||
WithDispatch {
|
||||
@ -97,7 +189,7 @@ pub trait WithSubscriber: Sized {
|
||||
}
|
||||
}
|
||||
|
||||
/// A future, stream, or sink that has been instrumented with a `tracing` span.
|
||||
/// A future, stream, sink, or executor that has been instrumented with a `tracing` span.
|
||||
#[cfg_attr(feature = "std-future", pin_project)]
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct Instrumented<T> {
|
||||
@ -129,7 +221,7 @@ impl<T: Sized> Instrument for T {}
|
||||
impl<T: std::future::Future> std::future::Future for Instrumented<T> {
|
||||
type Output = T::Output;
|
||||
|
||||
fn poll(self: Pin<&mut Self>, cx: &mut Context) -> std::task::Poll<Self::Output> {
|
||||
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> std::task::Poll<Self::Output> {
|
||||
let this = self.project();
|
||||
let _enter = this.span.enter();
|
||||
this.inner.poll(cx)
|
||||
@ -210,7 +302,7 @@ impl<T: futures::Future> futures::Future for WithDispatch<T> {
|
||||
impl<T: std::future::Future> std::future::Future for WithDispatch<T> {
|
||||
type Output = T::Output;
|
||||
|
||||
fn poll(self: Pin<&mut Self>, cx: &mut Context) -> std::task::Poll<Self::Output> {
|
||||
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> std::task::Poll<Self::Output> {
|
||||
let this = self.project();
|
||||
let dispatch = this.dispatch;
|
||||
let future = this.inner;
|
||||
@ -243,11 +335,12 @@ impl<T> WithDispatch<T> {
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
pub use self::support as test_support;
|
||||
pub(crate) use self::support as test_support;
|
||||
// This has to have the same name as the module in `tracing`.
|
||||
#[path = "../../tracing/tests/support/mod.rs"]
|
||||
#[cfg(test)]
|
||||
pub mod support;
|
||||
#[allow(unreachable_pub)]
|
||||
pub(crate) mod support;
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
@ -279,10 +372,8 @@ mod tests {
|
||||
|
||||
#[cfg(feature = "futures-01")]
|
||||
mod futures_tests {
|
||||
extern crate tokio;
|
||||
|
||||
use futures::{future, stream, task, Async, Future};
|
||||
use tracing::{subscriber::with_default, Level};
|
||||
use tracing::subscriber::with_default;
|
||||
|
||||
use super::*;
|
||||
|
||||
@ -315,7 +406,7 @@ mod tests {
|
||||
.run_with_handle();
|
||||
with_default(subscriber, || {
|
||||
PollN::new_ok(2)
|
||||
.instrument(span!(Level::TRACE, "foo"))
|
||||
.instrument(tracing::trace_span!("foo"))
|
||||
.wait()
|
||||
.unwrap();
|
||||
});
|
||||
@ -335,7 +426,7 @@ mod tests {
|
||||
.run_with_handle();
|
||||
with_default(subscriber, || {
|
||||
PollN::new_err(2)
|
||||
.instrument(span!(Level::TRACE, "foo"))
|
||||
.instrument(tracing::trace_span!("foo"))
|
||||
.wait()
|
||||
.unwrap_err();
|
||||
});
|
||||
@ -358,7 +449,7 @@ mod tests {
|
||||
.run_with_handle();
|
||||
with_default(subscriber, || {
|
||||
stream::iter_ok::<_, ()>(&[1, 2, 3])
|
||||
.instrument(span!(Level::TRACE, "foo"))
|
||||
.instrument(tracing::trace_span!("foo"))
|
||||
.for_each(|_| future::ok(()))
|
||||
.wait()
|
||||
.unwrap();
|
||||
@ -381,11 +472,11 @@ mod tests {
|
||||
.run_with_handle();
|
||||
let mut runtime = tokio::runtime::Runtime::new().unwrap();
|
||||
with_default(subscriber, || {
|
||||
span!(Level::TRACE, "a").in_scope(|| {
|
||||
tracing::trace_span!("a").in_scope(|| {
|
||||
let future = PollN::new_ok(2)
|
||||
.instrument(span!(Level::TRACE, "b"))
|
||||
.instrument(tracing::trace_span!("b"))
|
||||
.map(|_| {
|
||||
span!(Level::TRACE, "c").in_scope(|| {
|
||||
tracing::trace_span!("c").in_scope(|| {
|
||||
// "c" happens _outside_ of the instrumented future's
|
||||
// span, so we don't expect it.
|
||||
})
|
||||
|
||||
@ -22,7 +22,7 @@ default = ["tower-layer", "tower-util", "http"]
|
||||
|
||||
[dependencies]
|
||||
tracing = "0.1"
|
||||
tracing-futures = { version = "0.0.1-alpha.1", path = "../tracing-futures" }
|
||||
tracing-futures = { version = "0.1.0", path = "../tracing-futures" }
|
||||
futures = "0.1"
|
||||
tower-service = "0.2"
|
||||
tower-layer = { version = "0.1", optional = true }
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user