Add common guidance on recording errors on spans and metrics, clarify DB conventions

[lmolkova]

Fixes #1536, #1516

• Document HTTP + DB approach for span status + description as generic for spans
• Document error.type as generic error attribute on spans and metrics
• Specify how to classify db.response.status_codes as failures
• Update recommendation to record exceptions as a span events or log records

Important

We can and should implement strategy of reporting exceptions on local root spans in OTel SDK - it should not be an instrumentation concern.

Here's an OTEP on how to record exceptions on logs - it discusses the details of configurable exception recording strategy.
Since public facing log API is in development, we'll keep using span events for the time being.

Merge requirement checklist

• CONTRIBUTING.md guidelines followed.
• Change log entry added, according to the guidelines in When to add a changelog entry.
  • If your PR does not need a change log, start the PR title with [chore]
• schema-next.yaml updated with changes to existing conventions.

[Copilot]

Copilot reviewed 5 out of 20 changed files in this pull request and generated no comments.

Files not reviewed (15)

• docs/database/redis.md: Evaluated as low risk
• docs/database/cassandra.md: Evaluated as low risk
• docs/database/cosmosdb.md: Evaluated as low risk
• docs/rpc/rpc-spans.md: Evaluated as low risk
• docs/messaging/messaging-spans.md: Evaluated as low risk
• docs/cli/cli-spans.md: Evaluated as low risk
• docs/http/http-spans.md: Evaluated as low risk
• docs/general/recording-errors.md: Evaluated as low risk
• docs/gen-ai/gen-ai-spans.md: Evaluated as low risk
• docs/faas/faas-spans.md: Evaluated as low risk
• docs/exceptions/README.md: Evaluated as low risk
• docs/database/elasticsearch.md: Evaluated as low risk
• docs/database/database-spans.md: Evaluated as low risk
• docs/database/mongodb.md: Evaluated as low risk
• docs/database/couchdb.md: Evaluated as low risk

[jsuereth]

This looks good to me, but we may want to give some vendors extra time to adjust to the new span status guidance.

[lmolkova]

@jsuereth I'm fine keeping it open, I don't think it's necessary though:

The only change from what we recommend today is to stop recording handled exceptions and stop reporting exception.escaped attribute. AFAIK OTel instrumentations in general don't report handled exceptions anyway.

The exception.escaped attribute has even lower risk:

• Java does not use it in core repo, does not set it in -instrumentation or -contrib
• .NET does not use it, not used in the contrib either
• JS does not use it, also not used in the js-contrib
• Python sets this attribute, but incorrectly (always to string "False" and there is nothing that ever calls this method in contrib providing this flag)
• Go does not set it for obvious reasons
• I don't see any mention beyond definition in C++ (core or contrib) or in Rust.

So I think the guidance just catches up with existing practice and vendors don't need to change anything. I'll announce it at the Maintainers call on Mon 1/13 and Spec call on 1/14 to make sure everyone is aware.

Unless there is some pushback, I'm going to merge it on ~1/15.