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.
yordis
commented
1 day ago
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.namein 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.namecan 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