Recommend configuring `await-holding-invalid-types` in `Span::enter` documentation

[BatmanAoD]

Feature Request

Original title: "Explicitly allow the clippy::disallowed_methods lint in code generated by the tracing::instrument attribute-macro"

Crates

tracing-attributes

Motivation

The Span::enter() and Span::entered() methods recommend avoiding usage with async code, because they return span-guards that are applied to the entire thread.

Proposal

Recommend enabling the await-holding-invalid-types lint, and adding the following to clippy.toml:

await-holding-invalid-types = [
    { path = "tracing::span::Entered", reason = "generates incorrect spans when held across 'await' points" },
    { path = "tracing::span::EnteredSpan", reason = "generates incorrect spans when held across 'await' points" },
]

Alternatives

A project could fully prohibit usage of enter() or entered() within the codebase by adding those methods to the Clippy config for the disallowed_methods lint. However, the tracing::instrument attribute-macro uses enter() (while preventing holding the guard across await points). So if the codebase uses this macro, then the disallowed_methods lint will fire on every use of tracing::instrument.

The definition of the tracing::instrument macro could generate an allow attribute on each use of enter(), or on the entire generated polling function. (It should not be an expect, since the code has no way of knowing whether enter is configured as a disallowed method.)

[BatmanAoD]

...I've rewritten the request as a documentation request after realizing that there's a better clippy lint for this.

[hds]

Your original title is the same as the current title. Which doesn't seem to match the contents of the issue, or perhaps I'm reading it wrong?

[BatmanAoD]

Oops, no, I forgot that editing the title and editing the message body are separate operations in github (they're combined in gitlab), so I must have forgotten to submit a revised title.

[hds]

I think this makes sense. Would you like to open a PR?

[mladedav]

This is a great suggestion, it just happened to help me finding out why some of our spans were never closed and kept eating up our memory. I didn't even know clippy had this.