feat(rt/tracing): introduce tracing executors

[cratelyn]

📜 background

see #322 for more information.

in #166, hyper_util::rt::TokioExecutor<E> began propagating the currently active tracing::Span to spawned tasks when hyper::rt::Executor::execute() is called.

hyperium/hyper#3904 reports how this has since caused some issues, in part because some observability systems do not export spans until they are closed. in #322, we removed this behavior from hyper_util::rt::TokioExecutor<E>, with a temporary feature flag that can be used to preserve the previous behavior.

📊 rt::tracing

this branch introduces a new submodule, hyper_util::rt::tracing. this submodule contains a collection of Execute wrappers to allow tracing spans to be propagated according to a few different common strategies.

• WithSpanExecutor<E> instruments background tasks with a provided span.
• CurrentSpanExecutor<E> instruments background tasks with the current span when execute() is called.
• MkSpanExecutor<E, F> instruments background tasks with a span created by a provided callback.

this submodule is gated by the #[cfg(tracing)] feature flag.

🌱 Example

this branch adds an example similar to client.rs that makes use of the tracing functionality in rt::tracing. this example uses the current span executor, and runs the client in an info-level span to demonstrate the functionality.

the fmt feature is added to our development dependency upon tracing_subscriber.

when run against the server example, the logs look like the following:

; cargo run --example client_tracing --features 'client client-legacy http1 tokio tracing' -- http://127.0.0.1:8000

2026-09-21T18:12:10.840038Z  INFO client_tracing: tracing subscriber initialized
2026-09-21T18:12:10.840072Z  INFO client_tracing: parsed URL url=http://127.0.0.1:8000/
2026-09-21T18:12:10.840137Z TRACE sending request{url=http://127.0.0.1:8000/}: hyper_util::client::legacy::pool: checkout waiting for idle connection: ("http", 127.0.0.1:8000)
2026-09-21T18:12:10.840181Z TRACE sending request{url=http://127.0.0.1:8000/}: hyper_util::client::legacy::connect::http: Http::connect; scheme=Some("http"), host=Some("127.0.0.1"), port=Some(Port(8000))
2026-09-21T18:12:10.840199Z DEBUG sending request{url=http://127.0.0.1:8000/}: hyper_util::client::legacy::connect::http: connecting to 127.0.0.1:8000
2026-09-21T18:12:10.840335Z DEBUG sending request{url=http://127.0.0.1:8000/}: hyper_util::client::legacy::connect::http: connected to 127.0.0.1:8000
2026-09-21T18:12:10.840369Z TRACE sending request{url=http://127.0.0.1:8000/}: hyper_util::client::legacy::client: http1 handshake complete, spawning background dispatcher task
2026-09-21T18:12:10.840386Z TRACE sending request{url=http://127.0.0.1:8000/}: hyper_util::client::legacy::client: waiting for connection to be ready
2026-09-21T18:12:10.840422Z TRACE sending request{url=http://127.0.0.1:8000/}: hyper_util::client::legacy::client: connection is ready
2026-09-21T18:12:10.840432Z TRACE sending request{url=http://127.0.0.1:8000/}: hyper_util::client::legacy::pool: checkout dropped for ("http", 127.0.0.1:8000)
2026-09-21T18:12:10.840666Z TRACE sending request{url=http://127.0.0.1:8000/}: hyper_util::client::legacy::pool: put; add idle connection for ("http", 127.0.0.1:8000)
2026-09-21T18:12:10.840689Z DEBUG sending request{url=http://127.0.0.1:8000/}: hyper_util::client::legacy::pool: pooling idle connection for ("http", 127.0.0.1:8000)
2026-09-21T18:12:10.840709Z  INFO client_tracing: received response resp.version=HTTP/1.1 resp.status=200 OK resp.body=Hello, world!

this demonstrates the informative context (the destination url in this case) that is attached to background tasks spawned by the client.

[cratelyn]

💬 notes for reviewers

[cratelyn]

see the pr description for logs from this example.

[cratelyn]

i've added a link to the module-level documentation where there is more information about choosing a particular executor. we still mention CurrentSpanExecutor to provide a likely workable default for most users.

[cratelyn]

this is a test to show that we can spawn background tasks that "follow from" the current span. there is a bit of boilerplate to record and check this, since it isn't visible through Span's public interface: https://docs.rs/tracing/latest/tracing/struct.Span.html

[cratelyn]

because tracing spans can be a little bit tricky, i tried documenting this in a legible and descriptive way, and including examples (below) for some common span propagation strategies. open to suggestions about how to make this more helpful!