From 79d25b0a48d3e82a9d026e9cdfeef548153660ef Mon Sep 17 00:00:00 2001
From: Carl Lerche <me@carllerche.com>
Date: Mon, 14 Dec 2020 17:22:31 -0800
Subject: [PATCH] tracing: switch to unstable for 1.0. (#3266)

Enabling `tracing` integration now requires compiling with `--cfg
tokio_unstable`. Once `tracing-core` guarantees the same level of
stability as Tokio 1.0, unstable can be removed.

Closes #3258
---
 tokio/Cargo.toml            |  4 ++++
 tokio/README.md             |  3 +--
 tokio/src/lib.rs            | 10 +++++++++-
 tokio/src/macros/cfg.rs     |  4 ++--
 tokio/src/runtime/handle.rs |  4 ++--
 5 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/tokio/Cargo.toml b/tokio/Cargo.toml
index 89b99f6dd..7c0f84b30 100644
--- a/tokio/Cargo.toml
+++ b/tokio/Cargo.toml
@@ -102,6 +102,10 @@ mio = { version = "0.7.6", optional = true }
 num_cpus = { version = "1.8.0", optional = true }
 parking_lot = { version = "0.11.0", optional = true }
 slab = { version = "0.4.1", optional = true }
+
+# Currently unstable. The API exposed by these features may be broken at any time.
+# Requires `--cfg tokio_unstable` to enable.
+[target.'cfg(tokio_unstable)'.dependencies]
 tracing = { version = "0.1.21", default-features = false, features = ["std"], optional = true } # Not in full
 
 [target.'cfg(unix)'.dependencies]
diff --git a/tokio/README.md b/tokio/README.md
index 68ebc68e8..fb41b18da 100644
--- a/tokio/README.md
+++ b/tokio/README.md
@@ -133,8 +133,7 @@ several other libraries, including:
 
 * [`tower`]: A library of modular and reusable components for building robust networking clients and servers.
 
-* [`tracing`] (formerly `tokio-trace`): A framework for application-level
-  tracing and async-aware diagnostics.
+* [`tracing`]: A framework for application-level tracing and async-aware diagnostics.
 
 * [`rdbc`]: A Rust database connectivity library for MySQL, Postgres and SQLite.
 
diff --git a/tokio/src/lib.rs b/tokio/src/lib.rs
index 4e79c05d3..d5392b109 100644
--- a/tokio/src/lib.rs
+++ b/tokio/src/lib.rs
@@ -318,7 +318,6 @@
 //! - `signal`: Enables all `tokio::signal` types.
 //! - `fs`: Enables `tokio::fs` types.
 //! - `test-util`: Enables testing based infrastructure for the Tokio runtime.
-//! - `tracing`: Enables tracing events
 //!
 //! _Note: `AsyncRead` and `AsyncWrite` traits do not require any features and are
 //! always available._
@@ -333,6 +332,15 @@
 //! synchronization primitives internally. MSRV may increase according to the
 //! _parking_lot_ release in use.
 //!
+//! ### Unstable features
+//!
+//! These feature flags enable **unstable** features. The public API may break in 1.x
+//! releases. To enable these features, the `--cfg tokio_unstable` must be passed to
+//! `rustc` when compiling. This is easiest done using the `RUSTFLAGS` env variable:
+//! `RUSTFLAGS="--cfg tokio_unstable"`.
+//!
+//! - `tracing`: Enables tracing events.
+//!
 //! [feature flags]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section
 
 // Includes re-exports used by macros.
diff --git a/tokio/src/macros/cfg.rs b/tokio/src/macros/cfg.rs
index 15216560b..49cd66fb9 100644
--- a/tokio/src/macros/cfg.rs
+++ b/tokio/src/macros/cfg.rs
@@ -334,7 +334,7 @@ macro_rules! cfg_not_time {
 macro_rules! cfg_trace {
     ($($item:item)*) => {
         $(
-            #[cfg(feature = "tracing")]
+            #[cfg(all(tokio_unstable, feature = "tracing"))]
             #[cfg_attr(docsrs, doc(cfg(feature = "tracing")))]
             $item
         )*
@@ -344,7 +344,7 @@ macro_rules! cfg_trace {
 macro_rules! cfg_not_trace {
     ($($item:item)*) => {
         $(
-            #[cfg(not(feature = "tracing"))]
+            #[cfg(any(not(tokio_unstable), not(feature = "tracing")))]
             $item
         )*
     }
diff --git a/tokio/src/runtime/handle.rs b/tokio/src/runtime/handle.rs
index 138d13b25..6ff3c3930 100644
--- a/tokio/src/runtime/handle.rs
+++ b/tokio/src/runtime/handle.rs
@@ -142,7 +142,7 @@ impl Handle {
         F: Future + Send + 'static,
         F::Output: Send + 'static,
     {
-        #[cfg(feature = "tracing")]
+        #[cfg(all(tokio_unstable, feature = "tracing"))]
         let future = crate::util::trace::task(future, "task");
         self.spawner.spawn(future)
     }
@@ -172,7 +172,7 @@ impl Handle {
         F: FnOnce() -> R + Send + 'static,
         R: Send + 'static,
     {
-        #[cfg(feature = "tracing")]
+        #[cfg(all(tokio_unstable, feature = "tracing"))]
         let func = {
             #[cfg(tokio_track_caller)]
             let location = std::panic::Location::caller();