PCBC-1038, PCBC-1039: Add tracing & metrics instrumentation for non-management operations

[DemetrisChr]

Changes

• Add parentSpan option to all operation options blocks.
• Add instrumentation to all non-management operations (excluding data structures) to create the top-level operation span and metrics as described in the Extended Observability RFC. These make use of new helpers that DRY this logic (ObservabilityContext, ObservabilityHandler).
• Add NoopTracer and NoopMeter implementations which are the defaults for now, until the ThresholdLoggingMeter and LoggingMeter implementations are added.
• Include cluster name and cluster UUID attributes - fetched via the C++ Core API.

[Copilot]

Pull request overview

This pull request implements tracing and metrics instrumentation for non-management operations in the Couchbase PHP SDK, adding observability capabilities as described in the Extended Observability RFC.

Changes:

• Introduces observability infrastructure with ObservabilityWrapper and ObservabilityHandler classes to DRY instrumentation logic
• Adds parentSpan option to all operation options classes for distributed tracing support
• Implements NoopTracer, NoopSpan, NoopMeter, and NoopValueRecorder as default no-op implementations
• Instruments all non-management operations (KV, query, analytics, search, views) to create operation spans and record metrics
• Adds cluster name and UUID attributes fetched via the C++ Core API
• Provides comprehensive test coverage with test helpers (TestTracer, TestSpan, TestMeter, etc.) and test cases for KV and HTTP operations

Reviewed changes

Copilot reviewed 116 out of 116 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
Couchbase/Observability/ObservabilityWrapper.php	Core wrapper class that records operations with tracing and metrics
Couchbase/Observability/ObservabilityHandler.php	Handler for managing span creation, tagging, and metric recording
Couchbase/Observability/ObservabilityConstants.php	Centralized constants for operation names, attributes, and metric names
Couchbase/Observability/Keyspace.php	Represents bucket/scope/collection keyspace for tagging
Couchbase/Observability/StatusCode.php	Enum for span status codes
Couchbase/NoopTracer.php, NoopSpan.php, NoopMeter.php, NoopValueRecorder.php	Default no-op implementations
Couchbase/RequestTracer.php, RequestSpan.php, Meter.php	Interface updates for observability
Couchbase/Cluster.php, Bucket.php, Scope.php, Collection.php, BinaryCollection.php	Integration of observability wrapper in core SDK classes
Couchbase/ClusterOptions.php	Addition of tracer and meter configuration options
Couchbase/*Options.php (multiple files)	Addition of parentSpan option to all operation options
tests/Helpers/Tracing/*	Test infrastructure for tracing
tests/Helpers/Metrics/*	Test infrastructure for metrics
tests/Observability*Test.php	Comprehensive test coverage for KV and HTTP operations
src/wrapper/connection_handle.*	C++ wrapper for cluster labels functionality
src/php_couchbase.cxx	PHP extension function for cluster labels
Couchbase/Utilities/Deprecations.php	Fixed error message for durability level validation
Couchbase/JwtAuthenticator.php	Fixed formatting issue

Comments suppressed due to low confidence (1)

Couchbase/IncrementOptions.php:154

• The comment has improper indentation. It should be aligned with the code it documents at the same level as other method-level documentation.

        /**
     * @internal
     */

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[DemetrisChr]

I've pushed a change that renames ObservabilityWrapper to ObservabilityContext and also allows setting specific bucket/scope/collection names and service for the context. That avoids some of the boilerplate when calling recordOperation.

[avsej]

@DemetrisChr this failure looks related

 ✘ Scope level analytics query
   │
   │ expected exception to be not null and of type Couchbase\Exception\DataverseNotFoundException
   │ Failed asserting that null is not null.
   │
   │ /home/runner/work/couchbase-php-client/couchbase-php-client/tests/Helpers/CouchbaseTestCase.php:286
   │ /home/runner/work/couchbase-php-client/couchbase-php-client/tests/ObservabilityHttpOperationsTest.php:241
   │

[DemetrisChr]

@DemetrisChr this failure looks related

 ✘ Scope level analytics query
   │
   │ expected exception to be not null and of type Couchbase\Exception\DataverseNotFoundException
   │ Failed asserting that null is not null.
   │
   │ /home/runner/work/couchbase-php-client/couchbase-php-client/tests/Helpers/CouchbaseTestCase.php:286
   │ /home/runner/work/couchbase-php-client/couchbase-php-client/tests/ObservabilityHttpOperationsTest.php:241
   │

Another test is creating the _default dataverse, so this test might fail depending on which of the two tests runs first. I will update the test.