From 87c075e349cd25677fe646d0927c7a9cc75092e6 Mon Sep 17 00:00:00 2001 From: Eliza Weisman Date: Tue, 8 Oct 2019 13:48:54 -0700 Subject: [PATCH] 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 --- examples/Cargo.toml | 2 +- tracing-futures/CHANGELOG.md | 3 + tracing-futures/Cargo.toml | 12 +- tracing-futures/README.md | 36 +++-- tracing-futures/src/executor/futures_01.rs | 1 + tracing-futures/src/executor/tokio_alpha.rs | 8 - tracing-futures/src/lib.rs | 153 ++++++++++++++++---- tracing-tower/Cargo.toml | 2 +- 8 files changed, 160 insertions(+), 57 deletions(-) create mode 100644 tracing-futures/CHANGELOG.md diff --git a/examples/Cargo.toml b/examples/Cargo.toml index d4228e9e..53a8eed7 100644 --- a/examples/Cargo.toml +++ b/examples/Cargo.toml @@ -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" } diff --git a/tracing-futures/CHANGELOG.md b/tracing-futures/CHANGELOG.md new file mode 100644 index 00000000..dca54f34 --- /dev/null +++ b/tracing-futures/CHANGELOG.md @@ -0,0 +1,3 @@ +# 0.1.0 (Oct 8, 2019) + +- Initial release diff --git a/tracing-futures/Cargo.toml b/tracing-futures/Cargo.toml index aec7fde5..30a3e566 100644 --- a/tracing-futures/Cargo.toml +++ b/tracing-futures/Cargo.toml @@ -1,10 +1,10 @@ [package] name = "tracing-futures" -version = "0.0.1-alpha.2" +version = "0.1.0" authors = ["Eliza Weisman ", "Tokio Contributors "] 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" } diff --git a/tracing-futures/README.md b/tracing-futures/README.md index cde36b79..83e97514 100644 --- a/tracing-futures/README.md +++ b/tracing-futures/README.md @@ -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 diff --git a/tracing-futures/src/executor/futures_01.rs b/tracing-futures/src/executor/futures_01.rs index 74c45312..3d9cfe78 100644 --- a/tracing-futures/src/executor/futures_01.rs +++ b/tracing-futures/src/executor/futures_01.rs @@ -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")] diff --git a/tracing-futures/src/executor/tokio_alpha.rs b/tracing-futures/src/executor/tokio_alpha.rs index fbc1ba5a..eab3a7f2 100644 --- a/tracing-futures/src/executor/tokio_alpha.rs +++ b/tracing-futures/src/executor/tokio_alpha.rs @@ -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) { diff --git a/tracing-futures/src/lib.rs b/tracing-futures/src/lib.rs index 9a97762b..9c553552 100644 --- a/tracing-futures/src/lib.rs +++ b/tracing-futures/src/lib.rs @@ -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 { 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.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(self, subscriber: S) -> WithDispatch where S: Into, @@ -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 { 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 { @@ -129,7 +221,7 @@ impl Instrument for T {} impl std::future::Future for Instrumented { type Output = T::Output; - fn poll(self: Pin<&mut Self>, cx: &mut Context) -> std::task::Poll { + fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> std::task::Poll { let this = self.project(); let _enter = this.span.enter(); this.inner.poll(cx) @@ -210,7 +302,7 @@ impl futures::Future for WithDispatch { impl std::future::Future for WithDispatch { type Output = T::Output; - fn poll(self: Pin<&mut Self>, cx: &mut Context) -> std::task::Poll { + fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> std::task::Poll { let this = self.project(); let dispatch = this.dispatch; let future = this.inner; @@ -243,11 +335,12 @@ impl WithDispatch { } #[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. }) diff --git a/tracing-tower/Cargo.toml b/tracing-tower/Cargo.toml index cd62c05d..05fbe315 100644 --- a/tracing-tower/Cargo.toml +++ b/tracing-tower/Cargo.toml @@ -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 }