PCBC-1038: Add ThresholdLoggingTracer implementation

[DemetrisChr]

Motivation

When no external tracer is configured, the SDK must default to the ThresholdLoggingTracer. Now that spans are created on the PHP-side, we need to implement the ThresholdLoggingTracer PHP class.

Changes

• Implement the ThresholdLoggingTracer. It acts as a wrapper over the C++ core's tracer. When operation spans are created in the PHP wrapper code, the corresponding threshold logging spans are created in the C++ core.
• Add TracerException
• Create a core_span_resource that allows interacting with a C++ core span from PHP. This is only used for the ThresholdLoggingTracer.

[Copilot]

Pull request overview

Adds a PHP-side implementation of the default ThresholdLoggingTracer by introducing a PHP wrapper around a C++ core span resource, allowing spans created in PHP to be backed by the C++ core’s threshold-logging tracer.

Changes:

• Introduces a new core_span_resource and exposes coreSpanCreate/coreSpanEnd/coreSpanAddTag extension functions to manage core spans from PHP.
• Implements ThresholdLoggingTracer and ThresholdLoggingSpan in PHP, plus adds TracerException.
• Adjusts tracer selection so Cluster defaults to ThresholdLoggingTracer when no tracer is configured.

Reviewed changes

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

Show a summary per file

File	Description
src/wrapper/persistent_connections_cache.cxx	Removes a stray trailing line in the file footer.
src/wrapper/core_span_resource.hxx	Declares a new Zend resource wrapper for C++ core spans.
src/wrapper/core_span_resource.cxx	Implements core span resource creation, tagging, ending, and destruction behavior.
src/php_couchbase.cxx	Registers the new core span resource + adds PHP extension functions to create/end/tag spans.
Couchbase/ThresholdLoggingTracer.php	Implements ThresholdLoggingTracer backed by the extension’s core span functions.
Couchbase/ThresholdLoggingSpan.php	New PHP RequestSpan implementation that delegates to a core span resource.
Couchbase/RequestTracer.php	Updates the RequestTracer interface signature (return type + exception contract).
Couchbase/Exception/TracerException.php	Adds a new exception type for tracer/span misuse.
Couchbase/ClusterOptions.php	Changes getTracer() to return nullable, enabling defaulting logic in Cluster.
Couchbase/Cluster.php	Defaults to ThresholdLoggingTracer when no tracer is configured.

---

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