attributes: support recording error as std::error::Error

[magurotuna]

Motivation

While tracing::event! macro accepts a value that implements std::error::Error trait (that is, tracing::Value trait is implemented for dyn std::error::Error), there is no way to achieve the same thing when a function annotated with #[tracing::instrument] returns an error which implements std::error::Error; all we can do using the instrument attribute macro is something equivalent to either:

• event!(error = %e) (corresponds to err or err(Display))
• event!(error = ?e) (corresponds to err(Debug))

The lack of support of recording errors as std::error::Error becomes more apparent especially when we want to integrate them with OpenTelemetry. The tracing-opentelemetry crate provides a bridge layer, where it generates OTel's event that the chain of error causes based on a passed value implementing std::error::Error in accordance with Semantic Conventions for Exceptions on Spans. It would be really helpful in troubleshooting an error if its virtual stack trace was recorded and viewable in OTel-compatible tracing platform.

Solution

Added a new notation err(StdError) to the instrument attribute macro. This works in a very similar way to the existing err(Display) or err(Debug), with a difference that the returned error is converted into &dyn std::error::Error before being passed to the event! macro.

Consideration

It is very usual especially in application layer (as opposed to library layer) that error types are represented as the one provided by third party crates such as anyhow or eyre. Since the error types provided by them don't implement std::error::Error, we won't be able to use err(StdError) if an instrumented function returns, for example, anyhow::Error.

// This doesn't compile
#[tracing::instrument(err(StdError))]
fn foo() -> Result<(), anyhow::Error> {
    Ok(())
}

To support these types, I think the most straightforward approach would be to introduce another notation like err(AsRefStdError) that calls .as_ref() on the returned error before casting it into a trait object (note that AsRef<dyn std::error::Error> is implemented for third party error types). We could maybe revisit and consider how to deal with this case later.

Ref

#2648 pointed out that the instrument macro is limited to recording errors using either Display or Debug only, which doesn't really work well with OTel's semantic conventions on exceptions.

[kaffarell]

Glanced over the code and tested it quickly. Looks really good! IMO the AsRefStdError option is quite important as anyhow is really popular these days. This could be done in a follow-up PR though.