feat: implement Observability Phase 1 (Config, GAX Network, Auth Spans)

[cy-yun]

Description

This PR implements the foundational Phase 1 Telemetry & Tracing infrastructure in google-gax-php for Google Cloud PHP client libraries observability.

Following architectural review and alignment with cross-language project guidance:

• GAX-Centric Scope: All Phase 1 telemetry is encapsulated inside gax-php. google-auth-library-php and google-cloud-core remain 100% untouched and telemetry-agnostic.
• Strictly Non-Breaking & Zero Overhead: When tracing is not configured or disabled, all code paths execute with zero performance overhead.
• Cross-Language Semantic Alignment: Implements the relaxed GCP tracing attribute specification (convenient runtime/transport attributes included; attributes requiring proto descriptor parsing excluded).

---

Key Changes

1. Configuration & Feature Gating (TelemetryConfiguration)

• Added Google\ApiCore\Telemetry\TelemetryConfiguration to parse GOOGLE_SDK_PHP_TRACING_ENABLED.
• Enforces runtime precedence:
  1. Global Veto: GOOGLE_SDK_PHP_TRACING_ENABLED=false disables all tracing regardless of code settings.
  2. Auto-Discovery: GOOGLE_SDK_PHP_TRACING_ENABLED=true enables discovery via Globals::tracerProvider() (if present).
  3. Explicit Injection: Honors $options['openTelemetryTracerProvider'] passed via ClientOptions.
  4. Safe Default: Defaults to null (no-op) when unset.

2. Dependency Management

• Added open-telemetry/api: ^1.8 exclusively to Gax/composer.json.
• Updated root composer.json to bump google/gax to 1.50.0.
• Zero new dependencies added to Core or Auth.

3. T5 Internal Operation Spans

• RetryDelay: Emitted by RetryMiddleware across backoff sleep intervals. Injects rpc.method, http.request.resend_count, and standard GCP client attributes.
• RequestMarshaling & ResponseUnmarshaling: Emitted by RestTransport and GrpcFallbackTransport during request payload serialization and response hydration. Injects error/exception attributes on failure.
• AuthenticationRefresh (SpanKind::KIND_CLIENT): Implemented via Google\ApiCore\Telemetry\AuthHttpHandler decorator. Wrapped around PSR-7 $authHttpHandler during CredentialsWrapper initialization. Transparently intercepts token refresh HTTP calls without modifying google-auth-library-php, attaching rpc.system.name='http', http.request.method, url.full, server.address, server.port, http.response.status_code, and exception details. Handles both synchronous and promise-based (PromiseInterface) execution.

4. Client Options & Traits

• Added openTelemetryTracerProvider getter/setter to ClientOptions.
• Propagated tracer provider and client metadata (clientPackageName, libVersion, serviceName) through GapicClientTrait and ClientOptionsTrait.

[bshaffer]

There does not seem to be any integration here with our existing PSR-3 compliant logger. I think this difference will be confusing to our customers (and also to me, I am confused as to what the difference is already!)

Libraries exist which serve as adapters between the two (see https://packagist.org/packages/open-telemetry/opentelemetry-logger-monolog). This may be a good way to support it in the short term. A more robust solution would be to do something similar to what we already have with HttpHandler, where we have a factory which builds our own adapter class, and so we can be confident that the methods we expect exist already.

I would like to see either 1) the practical difference between loggerProvider and logger explained in the description and variable name, OR 2) a way to bridge the two (preferred)

[cy-yun]

thanks for the review!

I actually considered bridging this with PSR-3 (or using PSR-3 directly) in the initial design, but decided to keep loggerProvider (OpenTelemetry Logging API) separate from the existing PSR-3 logger.

The primary reason is trace-log correlation and structured attributes. The OpenTelemetry Logging API allows us to emit logs that are perfectly correlated with the current Trace ID and Span ID of the L4 network request (or T4 network spans), and it allows us to inject strongly-typed attributes (like gcp.errors.domain and gcp.errors.metadata.) directly into the log record's structured fields using LogRecordBuilder.

If we routed this through a PSR-3 adapter, we would lose this strict correlation and the native OTel structured logging capabilities required to link client-side traces to backend Google Cloud resources via App Hub.

I have updated the docblock in ClientOptions to explicitly clarify the practical difference between the two loggers so it's less confusing for users!

[cy-yun]

That's a very fair point about naming! Since PHP options are passed as untyped arrays, $options['logger'] and $options['loggerProvider'] do indeed look confusingly similar compared to languages with strictly-typed setters.

Looking at other languages:

• Node.js uses tracerProvider: TracerProvider directly in its options object.
• Python's google-api-core has tracer_provider as a kwargs argument.
• Java uses setTracerProvider().

However, since most of these languages don't heavily mix PSR-3 equivalent unstructured loggers in the exact same configuration array, they don't hit this naming collision as hard.

To eliminate the frustration and make it crystal clear, I've renamed them to explicitly prefix the OpenTelemetry origin. They are now openTelemetryTracerProvider and openTelemetryLoggerProvider in ClientOptions.

This directly communicates their origin (OpenTelemetry) and cleanly separates them from the legacy PSR-3 logger. The changes have been pushed and rebased across all dependent PRs. What do you think?

[bshaffer]

However, since most of these languages don't heavily mix PSR-3 equivalent unstructured loggers in the exact same configuration array, they don't hit this naming collision as hard.

I still think we could explore a way to resolve this issue, I cannot imagine the interfaces are that different

To eliminate the frustration and make it crystal clear, I've renamed them to explicitly prefix the OpenTelemetry origin. They are now openTelemetryTracerProvider and openTelemetryLoggerProvider in ClientOptions.

This is much better, I agree. Although if we are adding two new options to every single GAPIC client, I still would like to explore the purposes of these options in depth. Also, we will want to have a healthy comment block explaining their purpose.

The changes have been pushed and rebased across all dependent PRs.

I do not see any changes in this PR, can you make sure they were pushed?

[bshaffer]

Awaiting update from requested changes to ClientOptions names and description

[cy-yun]

I made the following fixes

1. Auth Span Attributes: AuthTracingMiddleware was setting rpc.system = http and rpc.service = auth. Since OAuth token fetches are standard HTTP client requests and not RPCs, I corrected these to use the standard OpenTelemetry HTTP semantic conventions: http.request.method and url.full.
2. HTTP Status Code Typing: In RestTransport.php, the HTTP status code was retrieved from Exception::getCode(), which can sometimes be a string or 0. Because OpenTelemetry attributes must be strictly typed, I explicitly cast the status code to an integer ((int) $statusCode) before emitting it to prevent validation errors in the Logger.