Clarify the usage of db.operation.name

[yordis]

Area(s)

area:db

Is your change request related to a problem? Please describe.

As per request from @trask from Slack:

There is confusion regarding the correct usage of db.operation.name in the OpenTelemetry database spans documentation.

The current examples and explanations suggest that db.operation.name should correspond to database-specific operations or commands (e.g., findAndModify), which has led to uncertainty among developers, including core maintainers, about whether this field can be used for the domain-specific language that is more relevant to the application context (e.g., fetchUserPreferences).

This ambiguity makes it difficult for users to identify the source of database calls in monitoring systems like CloudWatch, especially when SQL queries are too large or dynamic to be helpful in this context.

Describe the solution you'd like

The documentation should explicitly state that db.operation.name can be used as a free-form field specific to the application and not necessarily tied to database engine operations. It should clarify that developers can override the default names provided by instrumentation with more meaningful names that help identify the source of database calls within their domain.

Additionally, it would be beneficial to include examples demonstrating both database-specific and application-specific usages of db.operation.name, highlighting how it can be leveraged to improve traceability and monitoring.

Describe alternatives you've considered

No response

Additional context

No response

[yordis]

Hey @trask, any updates on this one?

[trask]

I agree that users should be allowed to override db.operation.name with something that makes more sense in their context, but I think in practice this would require open-telemetry/oteps#207