This documentation has an index for AI agents at /llms.txt. A Markdown version of this page is available at https://explorer.opentelemetry.io/java-agent/instrumentation/couchbase-2.0.md.

Couchbase Client

OpenTelemetry Java agent instrumentation

This instrumentation enables database client spans and database client metrics for Couchbase 2.0 operations. It automatically traces key-value operations (get, upsert, replace, remove), view queries, N1QL queries, and cluster management operations.

  • Name: couchbase-2.0
  • Scope: io.opentelemetry.couchbase-2.0
  • Target versions: com.couchbase.client:java-client:[2,3)
  • Library: https://github.com/couchbase/couchbase-java-client

Telemetry

When default

Spans

Span kindAttributes
CLIENTdb.name (STRING), db.operation (STRING), db.statement (STRING), db.system (STRING), network.peer.address (STRING), network.peer.port (LONG), network.type (STRING), server.address (STRING), server.port (LONG)

When otel.instrumentation.couchbase.emit-experimental-telemetry=true

Spans

Span kindAttributes
CLIENTcouchbase.local.address (STRING), couchbase.operation_id (STRING), db.name (STRING), db.operation (STRING), db.statement (STRING), db.system (STRING), network.peer.address (STRING), network.peer.port (LONG), network.type (STRING), server.address (STRING), server.port (LONG)

When otel.instrumentation.couchbase.experimental-span-attributes=true

Spans

Span kindAttributes
CLIENTcouchbase.local.address (STRING), couchbase.operation_id (STRING), db.name (STRING), db.operation (STRING), db.statement (STRING), db.system (STRING), network.peer.address (STRING), network.peer.port (LONG), network.type (STRING), server.address (STRING), server.port (LONG)

When otel.semconv-stability.opt-in=database

Metrics

MetricInstrumentTypeUnitDescription
db.client.operation.durationhistogramHISTOGRAMsDuration of database client operations.
MetricAttributes
db.client.operation.durationdb.operation.name (STRING), db.system.name (STRING), network.peer.address (STRING), network.peer.port (LONG), server.address (STRING)

Spans

Span kindAttributes
CLIENTdb.namespace (STRING), db.operation.name (STRING), db.query.summary (STRING), db.query.text (STRING), db.system.name (STRING), network.peer.address (STRING), network.peer.port (LONG), server.address (STRING)

Configuration

OptionTypeDefaultDescription
java.common.database.statement_sanitizer.enabledbooleantrueDeprecated: use java.common.db.query_sanitization.enabled instead. It is ignored under v3 preview.
otel.instrumentation.common.db-statement-sanitizer.enabledbooleantrueDeprecated: use otel.instrumentation.common.db.query-sanitization.enabled instead. It is ignored under v3 preview and will be removed in 3.0.
otel.instrumentation.common.db.query-sanitization.enabledbooleantrueEnables query sanitization for database queries.
otel.instrumentation.couchbase.emit-experimental-telemetrybooleanfalseEnables experimental span attributes couchbase.operation_id and couchbase.local.address. Different operation types receive different experimental attributes.
otel.instrumentation.couchbase.experimental-span-attributesbooleanfalseDeprecated and will be removed in the next minor release. Use otel.instrumentation.couchbase.emit-experimental-telemetry instead.
otel.instrumentation.couchbase.query-sanitization.enabledbooleanEnables query sanitization for Couchbase queries. Overrides otel.instrumentation.common.db.query-sanitization.enabled for this instrumentation; when unset, that setting applies.
otel.instrumentation.couchbase.statement-sanitizer.enabledbooleanDeprecated: use otel.instrumentation.couchbase.query-sanitization.enabled instead. It is ignored under v3 preview and will be removed in 3.0. When unset, this setting falls back to otel.instrumentation.common.db.query-sanitization.enabled (including its deprecated aliases).

Data

  • JSON (latest): /data/javaagent/instrumentations/couchbase-2.0/latest.json
  • JSON (pinned): /data/javaagent/instrumentations/couchbase-2.0/couchbase-2.0-44f388a5eb42.json
  • Explore: /java-agent/instrumentation/couchbase-2.0