log: prepare to release 0.1.1 (tokio-rs#413)

* log: deprecate `TraceLogger` This deprecation was discussed in tokio-rs#369 (comment). This API should not be used, as the `tracing` crate's `log` and `log-always` features provide better implementations of the same functionality, and the implementation here contains some deadlocks that make it unusable in real-world use-cases. Closes tokio-rs#369 Signed-off-by: Eliza Weisman <[email protected]> * log: minor readme tweaks - Improve list of provded APIs - Remove Gitter Signed-off-by: Eliza Weisman <[email protected]> * log: prepare to release 0.1.1 ### Deprecated - `TraceLogger` (use `tracing`'s "log" and "log-always" feature flags instead) ### Fixed - Issues with `log/std` feature flag (tokio-rs#406) - Minor documentation issues (tokio-rs#405, tokio-rs#408) * fix deprecation warning on reexport * rustfmt Signed-off-by: Eliza Weisman <[email protected]>
stormshield-kg · Oct 29, 2019 · 6f00dbd · 6f00dbd
1 parent 5dc2b15
commit 6f00dbd
Show file tree

Hide file tree

Showing 4 changed files with 39 additions and 18 deletions.
diff --git a/tracing-log/CHANGELOG.md b/tracing-log/CHANGELOG.md
@@ -1,3 +1,14 @@
+# 0.1.1 (October 29, 2019)
+
+### Deprecated
+
+- `TraceLogger` (use `tracing`'s "log" and "log-always" feature flags instead)
+
+### Fixed
+
+- Issues with `log/std` feature flag (#406)
+- Minor documentation issues (#405, #408)
+
 # 0.1.0 (September 3, 2019)
 
 - Initial release
diff --git a/tracing-log/README.md b/tracing-log/README.md
@@ -7,13 +7,11 @@
 [![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)][discord-url]
 
 
 [crates-badge]: https://img.shields.io/crates/v/tracing-log.svg
@@ -26,8 +24,6 @@
 [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-experimental-blue.svg
@@ -41,16 +37,17 @@ by the [`log`] crate.
 
 This crate provides:
 
+- [`AsTrace`] and [`AsLog`] traits for converting between `tracing` and `log` types.
 - [`LogTracer`], a [`log::Log`] implementation that consumes [`log::Record`]s
-  and outputs them as [`tracing::Event`].
-- [`TraceLogger`], a [`tracing::Subscriber`] implementation that consumes
-  [`tracing::Event`]s and outputs [`log::Record`], allowing an existing logger
-  implementation to be used to record trace events.
+  and outputs them as [`tracing::Event`]s.
+- An [`env_logger`] module, with helpers for using the [`env_logger` crate]
+  with `tracing` (optional, enabled by the `env-logger` feature).
 
 [`tracing`]: https://crates.io/crates/tracing
 [`log`]: https://crates.io/crates/log
+[`AsTrace`]: https://docs.rs/tracing-log/latest/tracing_log/trait.AsTrace.html
+[`AsLog`]: https://docs.rs/tracing-log/latest/tracing_log/trait.AsLog.html
 [`LogTracer`]: https://docs.rs/tracing-log/latest/tracing_log/struct.LogTracer.html
-[`TraceLogger`]: https://docs.rs/tracing-log/latest/tracing_log/struct.TraceLogger.html
 [`log::Log`]: https://docs.rs/log/latest/log/trait.Log.html
 [`log::Record`]: https://docs.rs/log/latest/log/struct.Record.html
 [`tracing::Subscriber`]: https://docs.rs/tracing/latest/tracing/trait.Subscriber.html

diff --git a/tracing-log/src/lib.rs b/tracing-log/src/lib.rs
@@ -13,9 +13,6 @@
 //! - [`AsTrace`] and [`AsLog`] traits for converting between `tracing` and `log` types.
 //! - [`LogTracer`], a [`log::Log`] implementation that consumes [`log::Record`]s
 //!   and outputs them as [`tracing::Event`].
-//! - [`TraceLogger`], a [`tracing::Subscriber`] implementation that consumes
-//!   [`tracing::Event`]s and outputs [`log::Record`], allowing an existing logger
-//!   implementation to be used to record trace events.
 //! - An [`env_logger`] module, with helpers for using the [`env_logger` crate]
 //!   with `tracing` (optional, enabled by the `env-logger` feature).
 //!
@@ -50,8 +47,9 @@
 //!
 //! ## Convert tracing `Event`s to logs
 //!
-//! This conversion can be done with [`TraceLogger`], a [`Subscriber`] which
-//! records `tracing` spans and events and outputs log records.
+//! Enabling the ["log" and "log-always" feature flags][flags] on the `tracing`
+//! crate will cause all `tracing` spans and events to emit `log::Record`s as
+//! they occur.
 //!
 //! ## Caution: Mixing both conversions
 //!
@@ -67,8 +65,8 @@
 //! required to avoid infinitely converting between `Event` and `log::Record`.
 //!
 //! # Feature Flags
-//!
-//! * `trace-logger`: enables the `TraceLogger` type (on by default)
+//! * `trace-logger`: enables an experimental `log` subscriber, deprecated since
+//!   version 0.1.1.
 //! * `log-tracer`: enables the `LogTracer` type (on by default)
 //! * `env_logger`: enables the `env_logger` module, with helpers for working
 //!   with the [`env_logger` crate].
@@ -138,6 +136,11 @@ pub mod trace_logger;
 pub use self::log_tracer::LogTracer;
 
 #[cfg(feature = "trace-logger")]
+#[deprecated(
+    since = "0.1.1",
+    note = "use the `tracing` crate's \"log\" feature flag instead"
+)]
+#[allow(deprecated)]
 #[doc(inline)]
 pub use self::trace_logger::TraceLogger;
 

diff --git a/tracing-log/src/trace_logger.rs b/tracing-log/src/trace_logger.rs
@@ -4,10 +4,16 @@
 //! When a [`TraceLogger`] is set as the current subscriber, it will record
 //! traces by emitting [`log::Record`]s that can be collected by a logger.
 //!
+//! **Note**: This API has been deprecated since version 0.1.1. In order to emit
+//! `tracing` events as `log` records, the ["log" and "log-always" feature
+//! flags][flags] on the `tracing` crate should be used instead.
+//!
 //! [`log`]: https://docs.rs/log/0.4.8/log/index.html
 //! [`Subscriber`]: https://docs.rs/tracing/0.1.7/tracing/subscriber/trait.Subscriber.html
 //! [`TraceLogger`]: struct.TraceLogger.html
 //! [`log::Record`]: https://docs.rs/log/0.4.8/log/struct.Record.html
+//! [flags]: https://docs.rs/tracing/0.1.10/tracing/#crate-feature-flags
+#![deprecated(since = "0.1.1", note = "use the `tracing` crate's \"log\" feature flag instead")]
 use crate::AsLog;
 use std::{
     cell::RefCell,
@@ -27,7 +33,11 @@ use tracing_core::{
 /// A `tracing` [`Subscriber`] implementation that logs all recorded
 /// trace events.
 ///
-//. [`Subscriber`]: https://docs.rs/tracing/0.1.7/tracing/subscriber/trait.Subscriber.html
+/// **Note**: This API has been deprecated since version 0.1.1. In order to emit
+/// `tracing` events as `log` records, the ["log" and "log-always" feature
+/// flags][flags] on the `tracing` crate should be used instead.
+///
+/// [`Subscriber`]: https://docs.rs/tracing/0.1.7/tracing/subscriber/trait.Subscriber.html
 pub struct TraceLogger {
     settings: Builder,
     spans: Mutex<HashMap<Id, SpanLineBuilder>>,