diff --git a/README.md b/README.md index 83ec624a..b58c0b5e 100644 --- a/README.md +++ b/README.md @@ -201,10 +201,11 @@ async { } ``` -The span `_s` will be dropped at the end of the `async` block, _not_ when the -future created by the async block is complete. In practice, this means that -the span does not live long enough to instrument the future for its entire -lifetime. +The span guard `_s` will not exit until the future generated by the `async` block is complete. +Since futures and spans can be entered and exited _multiple_ times without them completing, +the span remains entered for as long as the future exists, rather than being entered only when +it is polled, leading to very confusing and incorrect output. +For more details, see [the documentation on closing spans](https://tracing.rs/tracing/span/index.html#closing-spans). There are two ways to instrument asynchronous code. The first is through the [`Future::instrument`](https://docs.rs/tracing-futures/0.2.0/tracing_futures/trait.Instrument.html#method.instrument) combinator: diff --git a/tracing/README.md b/tracing/README.md index 37670db7..ec882845 100644 --- a/tracing/README.md +++ b/tracing/README.md @@ -216,10 +216,11 @@ async { } ``` -The span `_s` will be dropped at the end of the `async` block, _not_ when the -future created by the async block is complete. In practice, this means that -the span does not live long enough to instrument the future for its entire -lifetime. +The span guard `_s` will not exit until the future generated by the `async` block is complete. +Since futures and spans can be entered and exited _multiple_ times without them completing, +the span remains entered for as long as the future exists, rather than being entered only when +it is polled, leading to very confusing and incorrect output. +For more details, see [the documentation on closing spans](https://tracing.rs/tracing/span/index.html#closing-spans). There are two ways to instrument asynchronous code. The first is through the [`Future::instrument`](https://docs.rs/tracing-futures/0.2.0/tracing_futures/trait.Instrument.html#method.instrument) combinator: