Gate Couchbase 3.x SDK-detail telemetry and normalize span kinds under v3 preview

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

After #19996, the javaagent owns the Couchbase SDK 3.x tracing adapters instead of relying on Couchbase's shaded OpenTelemetry bridges. This exposes historical differences across SDK versions that we should not preserve as the intended v3 behavior.

Couchbase emits two SDK-specific child spans:

• request_encoding, when an operation encodes a payload
• dispatch_to_server, once per dispatch attempt, including retries

These are not database semantic-convention spans. They are currently emitted whenever the SDK invokes the corresponding tracing callbacks, without an experimental-telemetry gate.

Span kinds also vary by SDK version. Older Couchbase bridges left all request spans as INTERNAL, including top-level database operations. Newer bridges marked every request span as CLIENT, including request_encoding. Neither behavior is an appropriate model for all spans.

The existing otel.instrumentation.couchbase.experimental-span-attributes configuration controls only selected Couchbase-specific attributes. Its name cannot naturally cover experimental child spans, and it should not define the v3 behavior.

Describe the solution you'd like

Define consistent Couchbase 3.x behavior when otel.instrumentation.common.v3-preview=true, across SDK 3.0.x, 3.1.x, 3.2 through 3.3, and 3.4+:

• Always emit top-level database operation spans as CLIENT.
• Do not emit request_encoding or dispatch_to_server by default.
• Add otel.instrumentation.couchbase.emit-experimental-telemetry, with declarative configuration java.couchbase.emit_experimental_telemetry/development.
• When that option is enabled, emit the SDK-detail child spans and Couchbase-specific experimental attributes.
• Emit request_encoding as INTERNAL.
• Choose and document a consistent kind for dispatch_to_server. CLIENT is reasonable if it represents a physical network attempt; INTERNAL may be preferable if both optional child spans are treated uniformly as SDK implementation details.
• Continue emitting standard database semantic-convention attributes regardless of the experimental option.
• Gate all non-semantic-convention Couchbase 3.x attributes consistently, including attributes currently copied directly from SDK callbacks.
• Under v3 preview, ignore the old otel.instrumentation.couchbase.experimental-span-attributes and java.couchbase.experimental_span_attributes/development settings. They must not enable attributes or child spans and should not produce a deprecation warning in preview mode.
• Preserve existing non-preview behavior as needed for the remaining 2.x release line. Couchbase 2.x behavior is otherwise outside the scope of this issue.

Suppression should happen at the shared Couchbase 3.x span-construction layer so every adapter behaves consistently. The SDK must still receive a non-null no-op RequestSpan, because it continues calling attribute, event, status, exception, and end methods on the returned object.

Add coverage for representative SDK versions in each compatibility range. Tests should verify default suppression, experimental opt-in, span kinds, retry dispatches, operations with and without payload encoding, and that the legacy configuration has no effect under v3 preview.

Describe alternatives you've considered

Keeping the SDK-version-specific behavior would preserve compatibility, but it would carry known bridge limitations into the agent-owned implementation.

Dropping the child spans unconditionally would produce simpler telemetry but remove encoding, dispatch latency, and retry-attempt diagnostics for users who rely on them. An experimental opt-in keeps those diagnostics available without adding non-standard spans by default.

Retaining experimental-span-attributes as an alias under v3 preview would reduce migration work, but v3 preview is intended to model the eventual v3 behavior and should not keep obsolete configuration names alive.

Additional context

This follows the review discussion in #19996. The follow-up should be implemented after that PR so it can use the consolidated agent-owned Couchbase 3.x tracing layer.

Tip

_{React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.}