feat(upgrade): introduce tracing as an optional unstable feature (#3326)

* feat(upgrade): introduce tracing as an optional unstable feature

This change allow users to opt out of tracing via the `tracing` crate
by adding tracing as an optional feature. This change is part of the
effort, outlined in #2874, to reach hyper 1.0.

- Introduce several macros that act as wrappers around the `tracing`
module's macros to allow for more concise syntax for conditional
compilation of `tracing` macro calls. As `tracing` is unstable,
the new `trace` module will facilitate transitioning `tracing`
to an optional feature, as outlined in #2874 and #3326.
- Refactor code to utilize tracing macros from the new `trace` module.
- Add a `rustc` configuration flag (`hyper_unstable_tracing`) that must be passed
to the compiler when using the `tracing` feature. Throw a compiler error if `tracing`
is enabled without the flag. Part of the effort to transtition `tracing` to an
unstable dependecy. See #3326 and #2874.
- Modify `package.metadata.docs.rs` in `Cargo.toml` to include `tracing`
to list of `features` and `--cfg hyper_unstable_tracing` to the list of
`rustdoc-args`.
- Add unstable section to `lib.rs` detailing unstable features. Add information about `tracing`
and `ffi` to unstable features section.
- Log errors as a field rather than part of a formatted string.

Closes #3319

BREAKING CHANGES: tracing is disabled by default and requires users to
  opt in to an unstable feature to revert to previous behavior.

Author: RamziA961

.github/workflows/CI.yml

@@ -144,7 +144,7 @@ jobs:
         uses: taiki-e/install-action@cargo-hack
 
       - name: check --feature-powerset
-        run: cargo hack check --feature-powerset --depth 2 --skip ffi -Z avoid-dev-deps
+        run: cargo hack check --feature-powerset --depth 2 --skip ffi,tracing -Z avoid-dev-deps
 
   ffi:
     name: Test C API (FFI)

Cargo.toml

@@ -29,14 +29,14 @@ http-body-util = { version = "=0.1.0-rc.3", optional = true }
 httparse = "1.8"
 h2 = { version = "0.3.9", optional = true }
 itoa = "1"
-tracing = { version = "0.1", default-features = false, features = ["std"] }
 pin-project-lite = "0.2.4"
 tokio = { version = "1", features = ["sync"] }
 
 # Optional
 
 httpdate = { version = "1.0", optional = true }
 libc = { version = "0.2", optional = true }
+tracing = { version = "0.1", default-features = false, features = ["std"], optional = true }
 want = { version = "0.3", optional = true }
 
 [dev-dependencies]
@@ -84,12 +84,15 @@ server = ["dep:httpdate"]
 # C-API support (currently unstable (no semver))
 ffi = ["dep:libc", "dep:http-body-util"]
 
+# Utilize tracing (currently unstable)
+tracing = ["dep:tracing"]
+
 # internal features used in CI
 nightly = []
 
 [package.metadata.docs.rs]
-features = ["ffi", "full"]
-rustdoc-args = ["--cfg", "docsrs", "--cfg", "hyper_unstable_ffi"]
+features = ["ffi", "full", "tracing"]
+rustdoc-args = ["--cfg", "docsrs", "--cfg", "hyper_unstable_ffi", "--cfg", "hyper_unstable_tracing"]
 
 [package.metadata.playground]
 features = ["full"]

src/body/length.rs

@@ -50,8 +50,6 @@ impl DecodedLength {
     /// Checks the `u64` is within the maximum allowed for content-length.
     #[cfg(any(feature = "http1", feature = "http2"))]
     pub(crate) fn checked_new(len: u64) -> Result<Self, crate::error::Parse> {
-        use tracing::warn;
-
         if len <= MAX_LEN {
             Ok(DecodedLength(len))
         } else {

src/client/conn/http1.rs

@@ -191,8 +191,7 @@ where
                     Err(_canceled) => panic!("dispatch dropped without returning error"),
                 },
                 Err(_req) => {
-                    tracing::debug!("connection was not ready");
-
+                    debug!("connection was not ready");
                     Err(crate::Error::new_canceled().with("connection was not ready"))
                 }
             }
@@ -219,7 +218,7 @@ where
                 }))
             }
             Err(req) => {
-                tracing::debug!("connection was not ready");
+                debug!("connection was not ready");
                 let err = crate::Error::new_canceled().with("connection was not ready");
                 Either::Right(future::err((err, Some(req))))
             }
@@ -478,7 +477,7 @@ impl Builder {
         let opts = self.clone();
 
         async move {
-            tracing::trace!("client handshake HTTP/1");
+            trace!("client handshake HTTP/1");
 
             let (tx, rx) = dispatch::channel();
             let mut conn = proto::Conn::new(io);

src/client/conn/http2.rs

@@ -146,7 +146,7 @@ where
                     Err(_canceled) => panic!("dispatch dropped without returning error"),
                 },
                 Err(_req) => {
-                    tracing::debug!("connection was not ready");
+                    debug!("connection was not ready");
 
                     Err(crate::Error::new_canceled().with("connection was not ready"))
                 }
@@ -174,7 +174,7 @@ where
                 }))
             }
             Err(req) => {
-                tracing::debug!("connection was not ready");
+                debug!("connection was not ready");
                 let err = crate::Error::new_canceled().with("connection was not ready");
                 Either::Right(future::err((err, Some(req))))
             }
@@ -407,7 +407,7 @@ where
         let opts = self.clone();
 
         async move {
-            tracing::trace!("client handshake HTTP/1");
+            trace!("client handshake HTTP/1");
 
             let (tx, rx) = dispatch::channel();
             let h2 = proto::h2::client::handshake(io, rx, &opts.h2_builder, opts.exec, opts.timer)

src/client/dispatch.rs

@@ -5,7 +5,6 @@ use http::{Request, Response};
 use http_body::Body;
 use pin_project_lite::pin_project;
 use tokio::sync::{mpsc, oneshot};
-use tracing::trace;
 
 use crate::{
     body::Incoming,

src/lib.rs

@@ -51,7 +51,20 @@
 //! - `server`: Enables the HTTP `server`.
 //!
 //! [feature flags]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section
-
+//!
+//! # Unstable Features
+//! hyper includes a set of unstable optional features that can be enabled through the use of a
+//! feature flag and a [configuration flag].
+//!
+//! The following is a list of feature flags and their corresponding `RUSTFLAG`:
+//! - `ffi`: Enables C API for hyper `hyper_unstable_ffi`.
+//! - `tracing`: Enables debug logging with `hyper_unstable_tracing`.
+//!
+//! Enabling an unstable feature is possible with the following `cargo` command, as of version `1.64.0`:
+//! ```notrust
+//! RUSTFLAGS="--cfg hyper_unstable_tracing" cargo rustc --features client,http1,http2,tracing --crate-type cdylib
+//!```
+//! [configuration flag]: https://doc.rust-lang.org/reference/conditional-compilation.html
 #[doc(hidden)]
 pub use http;
 
@@ -67,6 +80,10 @@ pub use crate::error::{Error, Result};
 
 #[macro_use]
 mod cfg;
+
+#[macro_use]
+mod trace;
+
 #[macro_use]
 mod common;
 pub mod body;

src/proto/h1/conn.rs

@@ -9,7 +9,6 @@ use bytes::{Buf, Bytes};
 use http::header::{HeaderValue, CONNECTION};
 use http::{HeaderMap, Method, Version};
 use httparse::ParserConfig;
-use tracing::{debug, error, trace};
 
 use super::io::Buffered;
 use super::{Decoder, Encode, EncodedBuf, Encoder, Http1Transaction, ParseContext, Wants};
@@ -439,7 +438,7 @@ where
 
         let result = ready!(self.io.poll_read_from_io(cx));
         Poll::Ready(result.map_err(|e| {
-            trace!("force_io_read; io error = {:?}", e);
+            trace!(error = %e, "force_io_read; io error");
             self.state.close();
             e
         }))
@@ -749,7 +748,9 @@ where
 
         // If still in Reading::Body, just give up
         match self.state.reading {
-            Reading::Init | Reading::KeepAlive => trace!("body drained"),
+            Reading::Init | Reading::KeepAlive => {
+                trace!("body drained")
+            }
             _ => self.close_read(),
         }
     }

src/proto/h1/decode.rs

@@ -4,7 +4,6 @@ use std::io;
 use std::usize;
 
 use bytes::Bytes;
-use tracing::{debug, trace};
 
 use crate::common::{task, Poll};
 

src/proto/h1/dispatch.rs

@@ -3,7 +3,6 @@ use std::error::Error as StdError;
 use crate::rt::{Read, Write};
 use bytes::{Buf, Bytes};
 use http::Request;
-use tracing::{debug, trace};
 
 use super::{Http1Transaction, Wants};
 use crate::body::{Body, DecodedLength, Incoming as IncomingBody};