Couchbase instrumentation should create spans with kind CLIENT instead of INTERNAL #14982
Description
Currently, the OpenTelemetry Java agent's instrumentation for Couchbase creates spans with kind: INTERNAL.
According to the OpenTelemetry semantic conventions for database client spans, the span kind for database calls should be CLIENT.[1][2] This is recommended when the database system runs in a different process than its client, which is the standard deployment model for Couchbase.[1]
The use of kind: CLIENT is crucial for tools that build service maps and dependency graphs based on telemetry data.[3] For instance, the service graph processor in Grafana Tempo relies on the span.kind being client to correctly identify and represent database dependencies.[3] When the kind is INTERNAL, these tools may incorrectly interpret the Couchbase interaction as an in-process operation, leading to an inaccurate representation of the application architecture.
While it is understood that the Couchbase Java SDK has a highly asynchronous, non-blocking architecture, the fundamental nature of the operation is a remote call to a database cluster. Aligning with the semantic conventions by using kind: CLIENT would:
- Improve the accuracy of service maps and dependency graphs.
- Provide a more intuitive and consistent representation of database interactions across different database instrumentations (e.g., JDBC, Redis).
- Enhance the user experience for developers and operators who rely on these visualizations to understand their system's topology and identify performance bottlenecks.
Given these points, I would like to request that the Couchbase instrumentation be updated to set the span kind to CLIENT for all remote database operations. If there are specific cases where an INTERNAL span is appropriate (e.g., for purely in-memory SDK operations), it would be beneficial to have clear documentation on when and why this occurs.