From 3f8280ae6994bdceecad0b511de2fb4b4d1d8553 Mon Sep 17 00:00:00 2001 From: Eliza Weisman Date: Tue, 18 Aug 2020 12:11:16 -0700 Subject: [PATCH] docs: consistent MSRV docs & policy explanation (#941) ## 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 --- README.md | 13 ++++ tracing-appender/README.md | 18 +++++ tracing-appender/src/lib.rs | 18 +++++ tracing-attributes/README.md | 20 ++++- tracing-attributes/src/lib.rs | 21 ++++- tracing-core/README.md | 24 +++++- tracing-core/src/lib.rs | 21 ++++- tracing-error/README.md | 18 ++++- tracing-error/src/lib.rs | 19 ++++- tracing-flame/README.md | 17 +++++ tracing-flame/src/lib.rs | 18 +++++ tracing-futures/README.md | 18 +++++ tracing-futures/src/lib.rs | 19 +++++ tracing-journald/README.md | 34 ++++++++- tracing-journald/src/lib.rs | 34 +++++++++ tracing-log/README.md | 18 +++++ tracing-log/src/lib.rs | 18 +++++ tracing-opentelemetry/README.md | 18 +++++ tracing-opentelemetry/src/lib.rs | 19 +++++ tracing-serde/Cargo.toml | 3 + tracing-serde/README.md | 32 ++++++-- tracing-serde/src/lib.rs | 127 +++++++++++++++++++++++++++++++ tracing-subscriber/README.md | 18 +++++ tracing-subscriber/src/lib.rs | 18 +++++ tracing/README.md | 38 +++++++-- tracing/src/lib.rs | 19 ++++- 26 files changed, 611 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 1e09cb0cbb..46d76caba6 100644 --- a/README.md +++ b/README.md @@ -253,6 +253,19 @@ attachment that `Future::instrument` does. [`Future::instrument`]: https://docs.rs/tracing-futures/latest/tracing_futures/trait.Instrument.html#method.instrument [instrument]: https://docs.rs/tracing/0.1.14/tracing/attr.instrument.html +## Supported Rust Versions + +Tracing is built against the latest stable release. The minimum supported +version is 1.40. The current Tracing version is not guaranteed to build on Rust +versions earlier than the minimum supported version. + +Tracing follows the same compiler support policies as the rest of the Tokio +project. The current stable Rust compiler and the three most recent minor +versions before it will always be supported. For example, if the current stable +compiler version is 1.45, the minimum supported version will not be increased +past 1.42, three minor versions prior. Increasing the minimum supported compiler +version is not considered a semver breaking change as long as doing so complies +with this policy. ## Getting Help diff --git a/tracing-appender/README.md b/tracing-appender/README.md index fb8e40b6c1..5607549c98 100644 --- a/tracing-appender/README.md +++ b/tracing-appender/README.md @@ -36,6 +36,10 @@ allows events and spans to be recorded in a non-blocking manner through a dedicated logging thread. It also provides a [`RollingFileAppender`][file_appender] that can be used with _or_ without the non-blocking writer. +*Compiler support: [requires `rustc` 1.40+][msrv]* + +[msrv]: #supported-rust-versions + ## Usage Add the following to your `Cargo.toml`: @@ -139,6 +143,20 @@ fn main() { [file_appender]: https://docs.rs/tracing-appender/latest/tracing_appender/rolling/struct.RollingFileAppender.html [fmt_subscriber]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.Subscriber.html +## Supported Rust Versions + +Tracing is built against the latest stable release. The minimum supported +version is 1.40. The current Tracing version is not guaranteed to build on Rust +versions earlier than the minimum supported version. + +Tracing follows the same compiler support policies as the rest of the Tokio +project. The current stable Rust compiler and the three most recent minor +versions before it will always be supported. For example, if the current stable +compiler version is 1.45, the minimum supported version will not be increased +past 1.42, three minor versions prior. Increasing the minimum supported compiler +version is not considered a semver breaking change as long as doing so complies +with this policy. + ## License This project is licensed under the [MIT license](../LICENSE). diff --git a/tracing-appender/src/lib.rs b/tracing-appender/src/lib.rs index 56509d4436..074ecd6499 100644 --- a/tracing-appender/src/lib.rs +++ b/tracing-appender/src/lib.rs @@ -7,6 +7,9 @@ //! a dedicated logging thread. It also provides a [`RollingFileAppender`][file_appender] that can //! be used with _or_ without the non-blocking writer. //! +//! *Compiler support: [requires `rustc` 1.40+][msrv]* +//! +//! [msrv]: #supported-rust-versions //! [file_appender]: ./rolling/struct.RollingFileAppender.html //! [tracing]: https://docs.rs/tracing/ //! @@ -104,6 +107,21 @@ //! .init(); //! # } //! ``` +//! +//! ## Supported Rust Versions +//! +//! Tracing is built against the latest stable release. The minimum supported +//! version is 1.40. The current Tracing version is not guaranteed to build on +//! Rust versions earlier than the minimum supported version. +//! +//! Tracing follows the same compiler support policies as the rest of the Tokio +//! project. The current stable Rust compiler and the three most recent minor +//! versions before it will always be supported. For example, if the current +//! stable compiler version is 1.45, the minimum supported version will not be +//! increased past 1.42, three minor versions prior. Increasing the minimum +//! supported compiler version is not considered a semver breaking change as +//! long as doing so complies with this policy. +//! #![doc(html_root_url = "https://docs.rs/tracing-appender/0.1.1")] #![doc( html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo.svg", diff --git a/tracing-attributes/README.md b/tracing-attributes/README.md index 0992de6119..e196ed6c4d 100644 --- a/tracing-attributes/README.md +++ b/tracing-attributes/README.md @@ -37,6 +37,10 @@ structured, event-based diagnostic information. This crate provides the Note that this macro is also re-exported by the main `tracing` crate. +*Compiler support: [requires `rustc` 1.40+][msrv]* + +[msrv]: #supported-rust-versions + ## Usage First, add this to your `Cargo.toml`: @@ -46,7 +50,6 @@ First, add this to your `Cargo.toml`: tracing-attributes = "0.1.10" ``` -*Compiler support: requires rustc 1.39+* This crate provides the `#[instrument]` attribute for instrumenting a function with a `tracing` [span]. For example: @@ -60,10 +63,23 @@ pub fn my_function(my_arg: usize) { } ``` - [`tracing`]: https://crates.io/crates/tracing [span]: https://docs.rs/tracing/latest/tracing/span/index.html +## Supported Rust Versions + +Tracing is built against the latest stable release. The minimum supported +version is 1.40. The current Tracing version is not guaranteed to build on Rust +versions earlier than the minimum supported version. + +Tracing follows the same compiler support policies as the rest of the Tokio +project. The current stable Rust compiler and the three most recent minor +versions before it will always be supported. For example, if the current stable +compiler version is 1.45, the minimum supported version will not be increased +past 1.42, three minor versions prior. Increasing the minimum supported compiler +version is not considered a semver breaking change as long as doing so complies +with this policy. + ## License This project is licensed under the [MIT license](LICENSE). diff --git a/tracing-attributes/src/lib.rs b/tracing-attributes/src/lib.rs index 18181c9aad..340151e60b 100644 --- a/tracing-attributes/src/lib.rs +++ b/tracing-attributes/src/lib.rs @@ -6,6 +6,10 @@ //! //! Note that this macro is also re-exported by the main `tracing` crate. //! +//! *Compiler support: [requires `rustc` 1.40+][msrv]* +//! +//! [msrv]: #supported-rust-versions +//! //! ## Usage //! //! First, add this to your `Cargo.toml`: @@ -15,8 +19,6 @@ //! tracing-attributes = "0.1.10" //! ``` //! -//! *Compiler support: requires rustc 1.39+* -//! //! The [`#[instrument]`][instrument] attribute can now be added to a function //! to automatically create and enter `tracing` [span] when that function is //! called. For example: @@ -35,6 +37,21 @@ //! [`tracing`]: https://crates.io/crates/tracing //! [span]: https://docs.rs/tracing/latest/tracing/span/index.html //! [instrument]: attr.instrument.html +//! +//! ## Supported Rust Versions +//! +//! Tracing is built against the latest stable release. The minimum supported +//! version is 1.40. The current Tracing version is not guaranteed to build on +//! Rust versions earlier than the minimum supported version. +//! +//! Tracing follows the same compiler support policies as the rest of the Tokio +//! project. The current stable Rust compiler and the three most recent minor +//! versions before it will always be supported. For example, if the current +//! stable compiler version is 1.45, the minimum supported version will not be +//! increased past 1.42, three minor versions prior. Increasing the minimum +//! supported compiler version is not considered a semver breaking change as +//! long as doing so complies with this policy. +//! #![doc(html_root_url = "https://docs.rs/tracing-attributes/0.1.10")] #![doc( html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo.svg", diff --git a/tracing-core/README.md b/tracing-core/README.md index 91b1877d14..fadb8696fd 100644 --- a/tracing-core/README.md +++ b/tracing-core/README.md @@ -53,8 +53,12 @@ The crate provides: In addition, it defines the global callsite registry and per-thread current dispatcher which other components of the tracing system rely on. -## Usage +*Compiler support: [requires `rustc` 1.40+][msrv]* + +[msrv]: #supported-rust-versions +## Usage + Application authors will typically not use this crate directly. Instead, they will use the [`tracing`] crate, which provides a much more fully-featured API. However, this crate's API will change very infrequently, so it may be used @@ -71,15 +75,13 @@ The following crate feature flags are available: * `std`: Depend on the Rust standard library (enabled by default). - `no_std` users may disable this feature with `default-features = false`: + `no_std` users may disable this feature with `default-features = false`: ```toml [dependencies] tracing-core = { version = "0.1.14", default-features = false } ``` - *Compiler support: requires rustc 1.39+* - **Note**:`tracing-core`'s `no_std` support requires `liballoc`. [`tracing`]: ../tracing @@ -94,6 +96,20 @@ The following crate feature flags are available: [`ValueSet`]: https://docs.rs/tracing-core/0.1.14/tracing_core/field/struct.ValueSet.html [`Dispatch`]: https://docs.rs/tracing-core/0.1.14/tracing_core/dispatcher/struct.Dispatch.html +## Supported Rust Versions + +Tracing is built against the latest stable release. The minimum supported +version is 1.40. The current Tracing version is not guaranteed to build on Rust +versions earlier than the minimum supported version. + +Tracing follows the same compiler support policies as the rest of the Tokio +project. The current stable Rust compiler and the three most recent minor +versions before it will always be supported. For example, if the current stable +compiler version is 1.45, the minimum supported version will not be increased +past 1.42, three minor versions prior. Increasing the minimum supported compiler +version is not considered a semver breaking change as long as doing so complies +with this policy. + ## License This project is licensed under the [MIT license](LICENSE). diff --git a/tracing-core/src/lib.rs b/tracing-core/src/lib.rs index 8ca2157455..42539b5817 100644 --- a/tracing-core/src/lib.rs +++ b/tracing-core/src/lib.rs @@ -23,6 +23,10 @@ //! In addition, it defines the global callsite registry and per-thread current //! dispatcher which other components of the tracing system rely on. //! +//! *Compiler support: [requires `rustc` 1.40+][msrv]* +//! +//! [msrv]: #supported-rust-versions +//! //! ## Usage //! //! Application authors will typically not use this crate directly. Instead, @@ -52,10 +56,23 @@ //! tracing-core = { version = "0.1.14", default-features = false } //! ``` //! -//! *Compiler support: requires rustc 1.39+* -//! //! **Note**:`tracing-core`'s `no_std` support requires `liballoc`. //! +//! ## Supported Rust Versions +//! +//! Tracing is built against the latest stable release. The minimum supported +//! version is 1.40. The current Tracing version is not guaranteed to build on +//! Rust versions earlier than the minimum supported version. +//! +//! Tracing follows the same compiler support policies as the rest of the Tokio +//! project. The current stable Rust compiler and the three most recent minor +//! versions before it will always be supported. For example, if the current +//! stable compiler version is 1.45, the minimum supported version will not be +//! increased past 1.42, three minor versions prior. Increasing the minimum +//! supported compiler version is not considered a semver breaking change as +//! long as doing so complies with this policy. +//! +//! //! [`span::Id`]: span/struct.Id.html //! [`Event`]: event/struct.Event.html //! [`Subscriber`]: subscriber/trait.Subscriber.html diff --git a/tracing-error/README.md b/tracing-error/README.md index 0784fe2c5b..d8de3f5fed 100644 --- a/tracing-error/README.md +++ b/tracing-error/README.md @@ -48,7 +48,9 @@ The crate provides the following: **Note**: This crate is currently experimental. -*Compiler support: requires `rustc` 1.39+* +*Compiler support: [requires `rustc` 1.40+][msrv]* + +[msrv]: #supported-rust-versions ## Usage @@ -181,6 +183,20 @@ fn main() { - [`ExtractSpanTrace`] extension trait, for extracting `SpanTrace`s from behind `dyn Error` trait objects. +## Supported Rust Versions + +Tracing is built against the latest stable release. The minimum supported +version is 1.40. The current Tracing version is not guaranteed to build on Rust +versions earlier than the minimum supported version. + +Tracing follows the same compiler support policies as the rest of the Tokio +project. The current stable Rust compiler and the three most recent minor +versions before it will always be supported. For example, if the current stable +compiler version is 1.45, the minimum supported version will not be increased +past 1.42, three minor versions prior. Increasing the minimum supported compiler +version is not considered a semver breaking change as long as doing so complies +with this policy. + ## Related Crates In addition to this repository, here are also several third-party crates which diff --git a/tracing-error/src/lib.rs b/tracing-error/src/lib.rs index f802309c18..61e33605ff 100644 --- a/tracing-error/src/lib.rs +++ b/tracing-error/src/lib.rs @@ -18,7 +18,9 @@ //! //! **Note**: This crate is currently experimental. //! -//! *Compiler support: requires `rustc` 1.39+* +//! *Compiler support: [requires `rustc` 1.40+][msrv]* +//! +//! [msrv]: #supported-rust-versions //! //! ## Feature Flags //! @@ -168,6 +170,21 @@ //! [subscriber layer]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/layer/trait.Layer.html //! [`tracing`]: https://docs.rs/tracing //! [`std::error::Error`]: https://doc.rust-lang.org/stable/std/error/trait.Error.html +//! +//! ## Supported Rust Versions +//! +//! Tracing is built against the latest stable release. The minimum supported +//! version is 1.40. The current Tracing version is not guaranteed to build on +//! Rust versions earlier than the minimum supported version. +//! +//! Tracing follows the same compiler support policies as the rest of the Tokio +//! project. The current stable Rust compiler and the three most recent minor +//! versions before it will always be supported. For example, if the current +//! stable compiler version is 1.45, the minimum supported version will not be +//! increased past 1.42, three minor versions prior. Increasing the minimum +//! supported compiler version is not considered a semver breaking change as +//! long as doing so complies with this policy. +//! #![cfg_attr(docsrs, feature(doc_cfg))] #![doc(html_root_url = "https://docs.rs/tracing-error/0.1.2")] #![doc( diff --git a/tracing-flame/README.md b/tracing-flame/README.md index eb060b58c7..33e4232102 100644 --- a/tracing-flame/README.md +++ b/tracing-flame/README.md @@ -26,6 +26,9 @@ flamegraph/flamechart. Flamegraphs/flamecharts are useful for identifying perfor bottlenecks in an application. For more details, see Brendan Gregg's [post] on flamegraphs. +*Compiler support: [requires `rustc` 1.40+][msrv]* + +[msrv]: #supported-rust-versions [post]: http://www.brendangregg.com/flamegraphs.html ## Usage @@ -101,6 +104,20 @@ span is entered relative to others and get an accurate visual trace of the execution of your program. This representation is best created with a _flamechart_, which _does not_ sort or collapse identical stack frames. +## Supported Rust Versions + +Tracing is built against the latest stable release. The minimum supported +version is 1.40. The current Tracing version is not guaranteed to build on Rust +versions earlier than the minimum supported version. + +Tracing follows the same compiler support policies as the rest of the Tokio +project. The current stable Rust compiler and the three most recent minor +versions before it will always be supported. For example, if the current stable +compiler version is 1.45, the minimum supported version will not be increased +past 1.42, three minor versions prior. Increasing the minimum supported compiler +version is not considered a semver breaking change as long as doing so complies +with this policy. + ## License This project is licensed under the [MIT license](LICENSE). diff --git a/tracing-flame/src/lib.rs b/tracing-flame/src/lib.rs index b804bd8561..f0a9588865 100644 --- a/tracing-flame/src/lib.rs +++ b/tracing-flame/src/lib.rs @@ -10,6 +10,9 @@ //! issues bottlenecks in an application. For more details, see Brendan Gregg's [post] //! on flamegraphs. //! +//! *Compiler support: [requires `rustc` 1.40+][msrv]* +//! +//! [msrv]: #supported-rust-versions //! [post]: http://www.brendangregg.com/flamegraphs.html //! //! ## Usage @@ -91,6 +94,21 @@ //! [`FlameLayer`]: struct.FlameLayer.html //! [`FlushGuard`]: struct.FlushGuard.html //! [`inferno-flamegraph`]: https://docs.rs/inferno/0.9.5/inferno/index.html#producing-a-flame-graph +//! +//! ## Supported Rust Versions +//! +//! Tracing is built against the latest stable release. The minimum supported +//! version is 1.40. The current Tracing version is not guaranteed to build on +//! Rust versions earlier than the minimum supported version. +//! +//! Tracing follows the same compiler support policies as the rest of the Tokio +//! project. The current stable Rust compiler and the three most recent minor +//! versions before it will always be supported. For example, if the current +//! stable compiler version is 1.45, the minimum supported version will not be +//! increased past 1.42, three minor versions prior. Increasing the minimum +//! supported compiler version is not considered a semver breaking change as +//! long as doing so complies with this policy. +//! #![doc( html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo.svg", issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/" diff --git a/tracing-futures/README.md b/tracing-futures/README.md index a30943efca..c6d4b36a12 100644 --- a/tracing-futures/README.md +++ b/tracing-futures/README.md @@ -51,6 +51,24 @@ The crate provides the following traits: [`Subscriber`]: https://docs.rs/tracing/latest/tracing/subscriber/index.html [`tracing`]: https://crates.io/tracing +*Compiler support: [requires `rustc` 1.40+][msrv]* + +[msrv]: #supported-rust-versions + +## Supported Rust Versions + +Tracing is built against the latest stable release. The minimum supported +version is 1.40. The current Tracing version is not guaranteed to build on Rust +versions earlier than the minimum supported version. + +Tracing follows the same compiler support policies as the rest of the Tokio +project. The current stable Rust compiler and the three most recent minor +versions before it will always be supported. For example, if the current stable +compiler version is 1.45, the minimum supported version will not be increased +past 1.42, three minor versions prior. Increasing the minimum supported compiler +version is not considered a semver breaking change as long as doing so complies +with this policy. + ## License This project is licensed under the [MIT license](LICENSE). diff --git a/tracing-futures/src/lib.rs b/tracing-futures/src/lib.rs index 46f7570df9..3d8b867082 100644 --- a/tracing-futures/src/lib.rs +++ b/tracing-futures/src/lib.rs @@ -15,6 +15,10 @@ //! * [`WithSubscriber`] allows a `tracing` [`Subscriber`] to be attached to a //! future, sink, stream, or executor. //! +//! *Compiler support: [requires `rustc` 1.40+][msrv]* +//! +//! [msrv]: #supported-rust-versions +//! //! # Feature flags //! //! This crate provides a number of feature flags that enable compatibility @@ -54,6 +58,21 @@ //! [`Instrument`]: trait.Instrument.html //! [`WithSubscriber`]: trait.WithSubscriber.html //! [`futures`]: https://crates.io/crates/futures +//! +//! ## Supported Rust Versions +//! +//! Tracing is built against the latest stable release. The minimum supported +//! version is 1.40. The current Tracing version is not guaranteed to build on +//! Rust versions earlier than the minimum supported version. +//! +//! Tracing follows the same compiler support policies as the rest of the Tokio +//! project. The current stable Rust compiler and the three most recent minor +//! versions before it will always be supported. For example, if the current +//! stable compiler version is 1.45, the minimum supported version will not be +//! increased past 1.42, three minor versions prior. Increasing the minimum +//! supported compiler version is not considered a semver breaking change as +//! long as doing so complies with this policy. +//! #![doc(html_root_url = "https://docs.rs/tracing-futures/0.2.4")] #![doc( html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo.svg", diff --git a/tracing-journald/README.md b/tracing-journald/README.md index ff18f8e649..fea35305bc 100644 --- a/tracing-journald/README.md +++ b/tracing-journald/README.md @@ -4,15 +4,14 @@ # tracing-journald -Support for logging [`tracing`][tracing] events natively to journald, preserving structured information. +Support for logging [`tracing`][tracing] events natively to [journald], +preserving structured information. [![Crates.io][crates-badge]][crates-url] [![Documentation (master)][docs-master-badge]][docs-master-url] [![MIT licensed][mit-badge]][mit-url] ![maintenance status][maint-badge] -[tracing]: https://github.com/tokio-rs/tracing/tree/master/tracing -[tracing-fmt]: https://github.com/tokio-rs/tracing/tree/master/tracing-journald [crates-badge]: https://img.shields.io/crates/v/tracing-journald.svg [crates-url]: https://crates.io/crates/tracing-journald [docs-master-badge]: https://img.shields.io/badge/docs-master-blue @@ -21,6 +20,35 @@ Support for logging [`tracing`][tracing] events natively to journald, preserving [mit-url]: LICENSE [maint-badge]: https://img.shields.io/badge/maintenance-experimental-blue.svg +## Overview + +[`tracing`] is a framework for instrumenting Rust programs to collect +scoped, structured, and async-aware diagnostics. `tracing-journald` provides a +[`tracing-subscriber::Layer`][layer] implementation for logging `tracing` spans +and events to [`systemd-journald`][journald], on Linux distributions that use +`systemd`. + +*Compiler support: [requires `rustc` 1.40+][msrv]* + +[msrv]: #supported-rust-versions +[`tracing`]: https://crates.io/crates/tracing +[layer]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/layer/trait.Layer.html +[journald]: https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html + +## Supported Rust Versions + +Tracing is built against the latest stable release. The minimum supported +version is 1.40. The current Tracing version is not guaranteed to build on Rust +versions earlier than the minimum supported version. + +Tracing follows the same compiler support policies as the rest of the Tokio +project. The current stable Rust compiler and the three most recent minor +versions before it will always be supported. For example, if the current stable +compiler version is 1.45, the minimum supported version will not be increased +past 1.42, three minor versions prior. Increasing the minimum supported compiler +version is not considered a semver breaking change as long as doing so complies +with this policy. + ## License This project is licensed under the [MIT license](LICENSE). diff --git a/tracing-journald/src/lib.rs b/tracing-journald/src/lib.rs index 044927df74..3abf507feb 100644 --- a/tracing-journald/src/lib.rs +++ b/tracing-journald/src/lib.rs @@ -1,3 +1,37 @@ +//! # tracing-journald +//! +//! Support for logging [`tracing`][tracing] events natively to [journald], +//! preserving structured information. +//! +//! ## Overview +//! +//! [`tracing`] is a framework for instrumenting Rust programs to collect +//! scoped, structured, and async-aware diagnostics. `tracing-journald` provides a +//! [`tracing-subscriber::Layer`][layer] implementation for logging `tracing` spans +//! and events to [`systemd-journald`][journald], on Linux distributions that +//! use `systemd`. +//! +//! *Compiler support: [requires `rustc` 1.40+][msrv]* +//! +//! [msrv]: #supported-rust-versions +//! [`tracing`]: https://crates.io/crates/tracing +//! [layer]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/layer/trait.Layer.html +//! [journald]: https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html +//! +//! ## Supported Rust Versions +//! +//! Tracing is built against the latest stable release. The minimum supported +//! version is 1.40. The current Tracing version is not guaranteed to build on +//! Rust versions earlier than the minimum supported version. +//! +//! Tracing follows the same compiler support policies as the rest of the Tokio +//! project. The current stable Rust compiler and the three most recent minor +//! versions before it will always be supported. For example, if the current +//! stable compiler version is 1.45, the minimum supported version will not be +//! increased past 1.42, three minor versions prior. Increasing the minimum +//! supported compiler version is not considered a semver breaking change as +//! long as doing so complies with this policy. +//! #![doc( html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo.svg", issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/" diff --git a/tracing-log/README.md b/tracing-log/README.md index c021caf328..ebfafdae7a 100644 --- a/tracing-log/README.md +++ b/tracing-log/README.md @@ -56,6 +56,24 @@ This crate provides: [`tracing::Subscriber`]: https://docs.rs/tracing/latest/tracing/trait.Subscriber.html [`tracing::Event`]: https://docs.rs/tracing/latest/tracing/struct.Event.html +*Compiler support: [requires `rustc` 1.40+][msrv]* + +[msrv]: #supported-rust-versions + +## Supported Rust Versions + +Tracing is built against the latest stable release. The minimum supported +version is 1.40. The current Tracing version is not guaranteed to build on Rust +versions earlier than the minimum supported version. + +Tracing follows the same compiler support policies as the rest of the Tokio +project. The current stable Rust compiler and the three most recent minor +versions before it will always be supported. For example, if the current stable +compiler version is 1.45, the minimum supported version will not be increased +past 1.42, three minor versions prior. Increasing the minimum supported compiler +version is not considered a semver breaking change as long as doing so complies +with this policy. + ## License This project is licensed under the [MIT license](LICENSE). diff --git a/tracing-log/src/lib.rs b/tracing-log/src/lib.rs index caf2791937..5835114884 100644 --- a/tracing-log/src/lib.rs +++ b/tracing-log/src/lib.rs @@ -16,6 +16,10 @@ //! - An [`env_logger`] module, with helpers for using the [`env_logger` crate] //! with `tracing` (optional, enabled by the `env-logger` feature). //! +//! *Compiler support: [requires `rustc` 1.40+][msrv]* +//! +//! [msrv]: #supported-rust-versions +//! //! # Usage //! //! ## Convert log records to tracing `Event`s @@ -71,6 +75,20 @@ //! * `env_logger`: enables the `env_logger` module, with helpers for working //! with the [`env_logger` crate]. //! +//! ## Supported Rust Versions +//! +//! Tracing is built against the latest stable release. The minimum supported +//! version is 1.40. The current Tracing version is not guaranteed to build on +//! Rust versions earlier than the minimum supported version. +//! +//! Tracing follows the same compiler support policies as the rest of the Tokio +//! project. The current stable Rust compiler and the three most recent minor +//! versions before it will always be supported. For example, if the current +//! stable compiler version is 1.45, the minimum supported version will not be +//! increased past 1.42, three minor versions prior. Increasing the minimum +//! supported compiler version is not considered a semver breaking change as +//! long as doing so complies with this policy. +//! //! [`init`]: struct.LogTracer.html#method.init //! [`init_with_filter`]: struct.LogTracer.html#method.init_with_filter //! [`AsTrace`]: trait.AsTrace.html diff --git a/tracing-opentelemetry/README.md b/tracing-opentelemetry/README.md index d9f239c302..e5aad44044 100644 --- a/tracing-opentelemetry/README.md +++ b/tracing-opentelemetry/README.md @@ -50,6 +50,10 @@ The crate provides the following types: [`tracing`]: https://crates.io/crates/tracing [OpenTelemetry]: https://opentelemetry.io/ +*Compiler support: [requires `rustc` 1.40+][msrv]* + +[msrv]: #supported-rust-versions + ## Examples ### Basic Usage @@ -94,6 +98,20 @@ $ firefox http://localhost:16686/ ![Jaeger UI](trace.png) +## Supported Rust Versions + +Tracing is built against the latest stable release. The minimum supported +version is 1.40. The current Tracing version is not guaranteed to build on Rust +versions earlier than the minimum supported version. + +Tracing follows the same compiler support policies as the rest of the Tokio +project. The current stable Rust compiler and the three most recent minor +versions before it will always be supported. For example, if the current stable +compiler version is 1.45, the minimum supported version will not be increased +past 1.42, three minor versions prior. Increasing the minimum supported compiler +version is not considered a semver breaking change as long as doing so complies +with this policy. + ## License This project is licensed under the [MIT license](LICENSE). diff --git a/tracing-opentelemetry/src/lib.rs b/tracing-opentelemetry/src/lib.rs index 8aa6cfafb9..578a0159bd 100644 --- a/tracing-opentelemetry/src/lib.rs +++ b/tracing-opentelemetry/src/lib.rs @@ -9,6 +9,10 @@ //! [OpenTelemetry]: https://opentelemetry.io //! [`tracing`]: https://github.com/tokio-rs/tracing //! +//! *Compiler support: [requires `rustc` 1.40+][msrv]* +//! +//! [msrv]: #supported-rust-versions +//! //! ### Special Fields //! //! Fields with an `otel.` prefix are reserved for this crate and have specific @@ -69,6 +73,21 @@ //! error!("This event will be logged in the root span."); //! }); //! ``` +//! +//! ## Supported Rust Versions +//! +//! Tracing is built against the latest stable release. The minimum supported +//! version is 1.40. The current Tracing version is not guaranteed to build on +//! Rust versions earlier than the minimum supported version. +//! +//! Tracing follows the same compiler support policies as the rest of the Tokio +//! project. The current stable Rust compiler and the three most recent minor +//! versions before it will always be supported. For example, if the current +//! stable compiler version is 1.45, the minimum supported version will not be +//! increased past 1.42, three minor versions prior. Increasing the minimum +//! supported compiler version is not considered a semver breaking change as +//! long as doing so complies with this policy. +//! #![deny(unreachable_pub)] #![cfg_attr(test, deny(warnings))] #![doc(html_root_url = "https://docs.rs/tracing-opentelemetry/0.7.0")] diff --git a/tracing-serde/Cargo.toml b/tracing-serde/Cargo.toml index 3695b4c96a..1dbcad89c9 100644 --- a/tracing-serde/Cargo.toml +++ b/tracing-serde/Cargo.toml @@ -21,5 +21,8 @@ keywords = ["logging", "tracing", "serialization"] serde = "1" tracing-core = { path = "../tracing-core", version = "0.1.2"} +[dev-dependencies] +serde_json = "1" + [badges] maintenance = { status = "experimental" } diff --git a/tracing-serde/README.md b/tracing-serde/README.md index 7abb23c381..78b9e08d49 100644 --- a/tracing-serde/README.md +++ b/tracing-serde/README.md @@ -4,8 +4,7 @@ # tracing-serde -An adapter for serializing `tracing` types using `serde`. - +An adapter for serializing [`tracing`] types using [`serde`]. [![Documentation][docs-badge]][docs-url] [![Documentation (master)][docs-master-badge]][docs-master-url] @@ -17,9 +16,9 @@ An adapter for serializing `tracing` types using `serde`. ## Overview -`tracing-serde` enables serializing `tracing` types using -`serde`. `tracing` is a framework for instrumenting Rust programs -to collect structured, event-based diagnostic information. +[`tracing`] is a framework for instrumenting Rust programs to collect +scoped, structured, and async-aware diagnostics.`tracing-serde` enables +serializing `tracing` types using [`serde`]. Traditional logging is based on human-readable text messages. `tracing` gives us machine-readable structured diagnostic @@ -37,6 +36,10 @@ and tracing data to monitor your services in production. The `tracing` crate provides the APIs necessary for instrumenting libraries and applications to emit trace data. +*Compiler support: [requires `rustc` 1.40+][msrv]* + +[msrv]: #supported-rust-versions + ## Usage First, add this to your `Cargo.toml`: @@ -47,8 +50,6 @@ tracing = "0.1" tracing-serde = "0.1" ``` -*Compiler support: requires rustc 1.39+* - Next, add this to your crate: ```rust @@ -97,6 +98,20 @@ After you implement your `Subscriber`, you can use your `tracing` subscriber (`JsonSubscriber` in the above example) to record serialized trace data. +## Supported Rust Versions + +Tracing is built against the latest stable release. The minimum supported +version is 1.40. The current Tracing version is not guaranteed to build on Rust +versions earlier than the minimum supported version. + +Tracing follows the same compiler support policies as the rest of the Tokio +project. The current stable Rust compiler and the three most recent minor +versions before it will always be supported. For example, if the current stable +compiler version is 1.45, the minimum supported version will not be increased +past 1.42, three minor versions prior. Increasing the minimum supported compiler +version is not considered a semver breaking change as long as doing so complies +with this policy. + ## License This project is licensed under the [MIT license](LICENSE). @@ -106,3 +121,6 @@ This project is licensed under the [MIT license](LICENSE). Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Tokio by you, shall be licensed as MIT, without any additional terms or conditions. + +[`tracing`]: https://crates.io/crates/tracing +[`serde`]: https://crates.io/crates/serde \ No newline at end of file diff --git a/tracing-serde/src/lib.rs b/tracing-serde/src/lib.rs index 9b4cc70f58..8acf4d6f41 100644 --- a/tracing-serde/src/lib.rs +++ b/tracing-serde/src/lib.rs @@ -1,3 +1,130 @@ +//! # tracing-serde +//! +//! An adapter for serializing [`tracing`] types using [`serde`]. +//! +//! [![Documentation][docs-badge]][docs-url] +//! [![Documentation (master)][docs-master-badge]][docs-master-url] +//! +//! [docs-badge]: https://docs.rs/tracing-serde/badge.svg +//! [docs-url]: https://docs.rs/tracing-serde +//! [docs-master-badge]: https://img.shields.io/badge/docs-master-blue +//! [docs-master-url]: https://tracing-rs.netlify.com/tracing_serde +//! +//! ## Overview +//! +//! [`tracing`] is a framework for instrumenting Rust programs to collect +//! scoped, structured, and async-aware diagnostics.`tracing-serde` enables +//! serializing `tracing` types using [`serde`]. +//! +//! Traditional logging is based on human-readable text messages. +//! `tracing` gives us machine-readable structured diagnostic +//! information. This lets us interact with diagnostic data +//! programmatically. With `tracing-serde`, you can implement a +//! `Subscriber` to serialize your `tracing` types and make use of the +//! existing ecosystem of `serde` serializers to talk with distributed +//! tracing systems. +//! +//! Serializing diagnostic information allows us to do more with our logged +//! values. For instance, when working with logging data in JSON gives us +//! pretty-print when we're debugging in development and you can emit JSON +//! and tracing data to monitor your services in production. +//! +//! The `tracing` crate provides the APIs necessary for instrumenting +//! libraries and applications to emit trace data. +//! +//! *Compiler support: [requires `rustc` 1.40+][msrv]* +//! +//! [msrv]: #supported-rust-versions +//! +//! ## Usage +//! +//! First, add this to your `Cargo.toml`: +//! +//! ```toml +//! [dependencies] +//! tracing = "0.1" +//! tracing-serde = "0.1" +//! ``` +//! +//! Next, add this to your crate: +//! +//! ```rust +//! use tracing_serde::AsSerde; +//! ``` +//! +//! Please read the [`tracing` documentation](https://docs.rs/tracing/latest/tracing/index.html) +//! for more information on how to create trace data. +//! +//! This crate provides the `as_serde` function, via the `AsSerde` trait, +//! which enables serializing the `Attributes`, `Event`, `Id`, `Metadata`, +//! and `Record` `tracing` values. +//! +//! For the full example, please see the [examples](../examples) folder. +//! +//! Implement a `Subscriber` to format the serialization of `tracing` +//! types how you'd like. +//! +//! ```rust +//! # use tracing_core::{Subscriber, Metadata, Event}; +//! # use tracing_core::span::{Attributes, Id, Record}; +//! # use std::sync::atomic::{AtomicUsize, Ordering}; +//! use tracing_serde::AsSerde; +//! use serde_json::json; +//! +//! pub struct JsonSubscriber { +//! next_id: AtomicUsize, // you need to assign span IDs, so you need a counter +//! } +//! +//! impl Subscriber for JsonSubscriber { +//! +//! fn new_span(&self, attrs: &Attributes<'_>) -> Id { +//! let id = self.next_id.fetch_add(1, Ordering::Relaxed); +//! let id = Id::from_u64(id as u64); +//! let json = json!({ +//! "new_span": { +//! "attributes": attrs.as_serde(), +//! "id": id.as_serde(), +//! }}); +//! println!("{}", json); +//! id +//! } +//! +//! fn event(&self, event: &Event<'_>) { +//! let json = json!({ +//! "event": event.as_serde(), +//! }); +//! println!("{}", json); +//! } +//! +//! // ... +//! # fn enabled(&self, _: &Metadata<'_>) -> bool { false } +//! # fn enter(&self, _: &Id) {} +//! # fn exit(&self, _: &Id) {} +//! # fn record(&self, _: &Id, _: &Record<'_>) {} +//! # fn record_follows_from(&self, _: &Id, _: &Id) {} +//! } +//! ``` +//! +//! After you implement your `Subscriber`, you can use your `tracing` +//! subscriber (`JsonSubscriber` in the above example) to record serialized +//! trace data. +//! +//! ## Supported Rust Versions +//! +//! Tracing is built against the latest stable release. The minimum supported +//! version is 1.40. The current Tracing version is not guaranteed to build on +//! Rust versions earlier than the minimum supported version. +//! +//! Tracing follows the same compiler support policies as the rest of the Tokio +//! project. The current stable Rust compiler and the three most recent minor +//! versions before it will always be supported. For example, if the current +//! stable compiler version is 1.45, the minimum supported version will not be +//! increased past 1.42, three minor versions prior. Increasing the minimum +//! supported compiler version is not considered a semver breaking change as +//! long as doing so complies with this policy. +//! +//! [`tracing`]: https://crates.io/crates/tracing +//! [`serde`]: https://crates.io/crates/serde #![doc(html_root_url = "https://docs.rs/tracing-serde/0.1.1")] #![doc( html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo.svg", diff --git a/tracing-subscriber/README.md b/tracing-subscriber/README.md index c5fc822817..85dafe25da 100644 --- a/tracing-subscriber/README.md +++ b/tracing-subscriber/README.md @@ -32,6 +32,24 @@ Utilities for implementing and composing [`tracing`][tracing] subscribers. [discord-url]: https://discord.gg/EeF3cQw [maint-badge]: https://img.shields.io/badge/maintenance-experimental-blue.svg +*Compiler support: [requires `rustc` 1.40+][msrv]* + +[msrv]: #supported-rust-versions + +## Supported Rust Versions + +Tracing is built against the latest stable release. The minimum supported +version is 1.40. The current Tracing version is not guaranteed to build on Rust +versions earlier than the minimum supported version. + +Tracing follows the same compiler support policies as the rest of the Tokio +project. The current stable Rust compiler and the three most recent minor +versions before it will always be supported. For example, if the current stable +compiler version is 1.45, the minimum supported version will not be increased +past 1.42, three minor versions prior. Increasing the minimum supported compiler +version is not considered a semver breaking change as long as doing so complies +with this policy. + ## License This project is licensed under the [MIT license](LICENSE). diff --git a/tracing-subscriber/src/lib.rs b/tracing-subscriber/src/lib.rs index f2a02a7ff3..c6d5ea7481 100644 --- a/tracing-subscriber/src/lib.rs +++ b/tracing-subscriber/src/lib.rs @@ -10,6 +10,10 @@ //! `tracing-subscriber` is intended for use by both `Subscriber` authors and //! application authors using `tracing` to instrument their applications. //! +//! *Compiler support: [requires `rustc` 1.40+][msrv]* +//! +//! [msrv]: #supported-rust-versions +//! //! ## Included Subscribers //! //! The following `Subscriber`s are provided for application authors: @@ -39,6 +43,20 @@ //! - [`parking_lot`]: Use the `parking_lot` crate's `RwLock` implementation //! rather than the Rust standard library's implementation. //! +//! ## Supported Rust Versions +//! +//! Tracing is built against the latest stable release. The minimum supported +//! version is 1.40. The current Tracing version is not guaranteed to build on +//! Rust versions earlier than the minimum supported version. +//! +//! Tracing follows the same compiler support policies as the rest of the Tokio +//! project. The current stable Rust compiler and the three most recent minor +//! versions before it will always be supported. For example, if the current +//! stable compiler version is 1.45, the minimum supported version will not be +//! increased past 1.42, three minor versions prior. Increasing the minimum +//! supported compiler version is not considered a semver breaking change as +//! long as doing so complies with this policy. +//! //! [`tracing`]: https://docs.rs/tracing/latest/tracing/ //! [`Subscriber`]: https://docs.rs/tracing-core/latest/tracing_core/subscriber/trait.Subscriber.html //! [`EnvFilter`]: filter/struct.EnvFilter.html diff --git a/tracing/README.md b/tracing/README.md index 1bb1aa2419..16bc5ef825 100644 --- a/tracing/README.md +++ b/tracing/README.md @@ -28,7 +28,6 @@ Application-level tracing for Rust. [discord-badge]: https://img.shields.io/discord/500028886025895936?logo=discord&label=discord&logoColor=white [discord-url]: https://discord.gg/EeF3cQw - ## Overview `tracing` is a framework for instrumenting Rust programs to collect @@ -48,7 +47,9 @@ data as well as textual messages. The `tracing` crate provides the APIs necessary for instrumenting libraries and applications to emit trace data. -*Compiler support: requires `rustc` 1.39+* +*Compiler support: [requires `rustc` 1.40+][msrv]* + +[msrv]: #supported-rust-versions ## Usage @@ -323,9 +324,23 @@ be invoked with the same syntax as the similarly-named macros from the `log` crate. Often, the process of converting a project to use `tracing` can begin with a simple drop-in replacement. -### Ecosystem +## Supported Rust Versions + +Tracing is built against the latest stable release. The minimum supported +version is 1.40. The current Tracing version is not guaranteed to build on Rust +versions earlier than the minimum supported version. + +Tracing follows the same compiler support policies as the rest of the Tokio +project. The current stable Rust compiler and the three most recent minor +versions before it will always be supported. For example, if the current stable +compiler version is 1.45, the minimum supported version will not be increased +past 1.42, three minor versions prior. Increasing the minimum supported compiler +version is not considered a semver breaking change as long as doing so complies +with this policy. + +## Ecosystem -## Related Crates +### Related Crates In addition to `tracing` and `tracing-core`, the [`tokio-rs/tracing`] repository contains several additional crates designed to be used with the `tracing` ecosystem. @@ -383,7 +398,6 @@ please let us know! We'd love to add your project to the list! undergoing active development. They may be less stable than `tracing` and `tracing-core`. - [`log`]: https://docs.rs/log/0.4.6/log/ [`tokio-rs/tracing`]: https://github.com/tokio-rs/tracing [`tracing-futures`]: https://github.com/tokio-rs/tracing/tree/master/tracing-futures @@ -393,6 +407,20 @@ undergoing active development. They may be less stable than `tracing` and [`FmtSubscriber`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.Subscriber.html [`examples`]: https://github.com/tokio-rs/tracing/tree/master/examples +## Supported Rust Versions + +Tracing is built against the latest stable release. The minimum supported +version is 1.40. The current Tracing version is not guaranteed to build on Rust +versions earlier than the minimum supported version. + +Tracing follows the same compiler support policies as the rest of the Tokio +project. The current stable Rust compiler and the three most recent minor +versions before it will always be supported. For example, if the current stable +compiler version is 1.45, the minimum supported version will not be increased +past 1.42, three minor versions prior. Increasing the minimum supported compiler +version is not considered a semver breaking change as long as doing so complies +with this policy. + ## License This project is licensed under the [MIT license](LICENSE). diff --git a/tracing/src/lib.rs b/tracing/src/lib.rs index 03f84f5a00..40660a3983 100644 --- a/tracing/src/lib.rs +++ b/tracing/src/lib.rs @@ -19,6 +19,9 @@ //! The `tracing` crate provides the APIs necessary for instrumenting libraries //! and applications to emit trace data. //! +//! *Compiler support: [requires `rustc` 1.40+][msrv]* +//! +//! [msrv]: #supported-rust-versions //! # Core Concepts //! //! The core of `tracing`'s API is composed of _spans_, _events_ and @@ -777,8 +780,6 @@ //! tracing = { version = "0.1.19", default-features = false } //! ``` //! -//! *Compiler support: requires rustc 1.39+* -//! //!
//!
ⓘNote
//!
@@ -788,6 +789,20 @@ //! requires liballoc. //! //! +//! ## Supported Rust Versions +//! +//! Tracing is built against the latest stable release. The minimum supported +//! version is 1.40. The current Tracing version is not guaranteed to build on +//! Rust versions earlier than the minimum supported version. +//! +//! Tracing follows the same compiler support policies as the rest of the Tokio +//! project. The current stable Rust compiler and the three most recent minor +//! versions before it will always be supported. For example, if the current +//! stable compiler version is 1.45, the minimum supported version will not be +//! increased past 1.42, three minor versions prior. Increasing the minimum +//! supported compiler version is not considered a semver breaking change as +//! long as doing so complies with this policy. +//! //! [`log`]: https://docs.rs/log/0.4.6/log/ //! [span]: span/index.html //! [`Span`]: span/struct.Span.html