Skip to content

feat(Gax): implement Observability Phase 1 (Config, Client Request & Network Tracing) - #9573

Open
cy-yun wants to merge 6 commits into
googleapis:mainfrom
cy-yun:feat/observability-t1-config
Open

feat(Gax): implement Observability Phase 1 (Config, Client Request & Network Tracing)#9573
cy-yun wants to merge 6 commits into
googleapis:mainfrom
cy-yun:feat/observability-t1-config

Conversation

@cy-yun

@cy-yun cy-yun commented Aug 25, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Description

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

Following cross-language project guidance, this PR is strictly focused on configuration/gating, Client Request (T3), and Network Request (T4) tracing. T5 internal operation spans (RetryDelay, RequestMarshaling, ResponseUnmarshaling, and AuthenticationRefresh) are decoupled and deferred to a follow-up PR.

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. Client Request Tracing (TracingMiddleware)

  • Implemented Google\ApiCore\Middleware\TracingMiddleware to wrap API calls in a top-level Client Request span (T3).
  • Records rpc.system.name, rpc.method, server.address, and server.port.
  • Safely manages span activation and detachment across both synchronous and promise-based (async) execution lifecycles.

3. Low-Level Network Tracing (GrpcTransport)

  • Added gRPC network attempt client spans (T4) directly inside GrpcTransport::startUnaryCall() with SpanKind::CLIENT.
  • Records SemConv 1.39 attributes (rpc.system.name="grpc", rpc.method, server.address, server.port, rpc.response.status_code).

4. Client Options & Traits

  • Added openTelemetryTracerProvider getter/setter to ClientOptions.
  • Propagated tracer provider and client metadata through GapicClientTrait and ClientOptionsTrait.
  • Added standard OpenTelemetry Semantic Convention 1.39 attribute constants in SpanAttributes.

5. Dependency Management

  • Added open-telemetry/api: ^1.8 exclusively to Gax/composer.json.
  • Zero new dependencies added to Core or Auth.

@cy-yun
cy-yun requested a review from a team as a code owner August 25, 2026 17:33
@cy-yun cy-yun mentioned this pull request Aug 25, 2026
Closed
@cy-yun
cy-yun force-pushed the feat/observability-t1-config branch from 2a16e32 to 14bda98 Compare August 25, 2026 20:47
@cy-yun
cy-yun marked this pull request as draft August 25, 2026 21:04
@cy-yun
cy-yun force-pushed the feat/observability-t1-config branch 3 times, most recently from 92de944 to 6c40ebc Compare August 25, 2026 21:44
@cy-yun
cy-yun marked this pull request as ready for review August 26, 2026 08:16
bshaffer
bshaffer reviewed Aug 26, 2026
View reviewed changes
Comment thread Gax/src/Options/ClientOptions.php Outdated
cy-yun

This comment was marked as duplicate.

Sign in to view

cy-yun

This comment was marked as resolved.

Sign in to view

@bshaffer

This comment was marked as resolved.

Sign in to view
bshaffer

This comment was marked as resolved.

Sign in to view

@cy-yun cy-yun changed the title feat: Add TelemetryConfiguration and Tracer/Logger options feat: implement Observability Phase 1 (Config, GAX Network, Auth Spans) Aug 28, 2026
This was referenced Aug 28, 2026
Closed
Closed
cy-yun

This comment was marked as resolved.

Sign in to view

@cy-yun
cy-yun force-pushed the feat/observability-t1-config branch 4 times, most recently from 77f7ce0 to 48af3f8 Compare August 31, 2026 21:23
@cy-yun
cy-yun requested a review from bshaffer September 1, 2026 21:15
@cy-yun
cy-yun force-pushed the feat/observability-t1-config branch 6 times, most recently from c42b831 to 7c957e0 Compare September 4, 2026 21:20
@cy-yun
cy-yun force-pushed the feat/observability-t1-config branch 2 times, most recently from 3d74452 to fd43fa5 Compare September 9, 2026 21:39
@cy-yun
cy-yun force-pushed the feat/observability-t1-config branch 10 times, most recently from 003f22e to 1c174c6 Compare September 15, 2026 21:27
@cy-yun
cy-yun force-pushed the feat/observability-t1-config branch 2 times, most recently from 24db6c4 to bba8086 Compare September 16, 2026 23:45
Hectorhammett
Hectorhammett reviewed Sep 17, 2026
View reviewed changes
Comment thread Core/src/Telemetry/AuthTracingMiddleware.php Outdated
Comment thread Gax/src/Options/ClientOptions.php Outdated
Comment thread Gax/src/Telemetry/SpanAttributes.php Outdated
Comment thread Gax/src/AgentHeader.php Outdated
Comment thread Gax/src/GapicClientTrait.php Outdated
@cy-yun
cy-yun force-pushed the feat/observability-t1-config branch 4 times, most recently from 7e0227d to 9803817 Compare September 22, 2026 01:18
@cy-yun cy-yun changed the title feat: implement Observability Phase 1 (Config, GAX Network, Auth Spans) feat(Gax): implement Observability Phase 1 (Config, Client Request & Network Tracing) Sep 23, 2026
cy-yun and others added 5 commits September 28, 2026 13:57
@cy-yun
feat(Gax): implement Observability Phase 1 (Config, GAX Network, Auth…
ca834de 
… Spans)
@cy-yun
fix(Gax): align OTel SemConv 1.39, DRY transport spans, and document …
2ca87e8 
…ClientOptions

- Align OpenTelemetry semantic conventions with v1.39 (server.address, server.port, rpc.system.name, rpc.response.status_code)
- Remove unreleased deprecated RPC_SYSTEM constant in favor of canonical RPC_SYSTEM_NAME
- Extract traceTransportOperation helper in TelemetryTrait to DRY transport operation tracing
- Explicitly record exceptions as span events via recordException()
- Add comprehensive docblocks explaining openTelemetryTracerProvider in ClientOptions
@cy-yun
fix(Gax): resolve scope detach lifecycle, transport scope activation,…
b0f54ec 
… and auth handler reconfiguration

- Synchronously detach OTel scope in TracingMiddleware to avoid leaking context across unawaited async calls
- Activate OTel span scope during promise wait() execution so retry delays and subsequent attempts inherit Client Request span context
- Activate and detach scope around transport operations in TelemetryTrait::traceTransportOperation
- Support reconfiguring TracerProviderInterface on already-wrapped AuthHttpHandler instances in CredentialsWrapper
- Modernize array destructuring syntax in GapicClientTrait
- Remove internal taxonomy shorthand from TracingMiddleware docblock
- Add unit test coverage for promise wait/cancellation scope lifecycles and AuthHttpHandler reconfiguration
@cy-yun
refactor(Gax): decouple T5 internal operation spans from initial PR
4362e8c 
Decouple T5 spans (RetryDelay, RequestMarshaling, ResponseUnmarshaling, and
AuthenticationRefresh) to focus the PR strictly on configuration/gating,
T3 (Client Request), and T4 (Network Request).
@cy-yun
fix(Gax): type TelemetryTrait property, clean up redundant assignment…
c907afa 
…s and unused attributes
@cy-yun
cy-yun force-pushed the feat/observability-t1-config branch from 7fa2649 to c907afa Compare September 28, 2026 20:58
@bshaffer

bshaffer commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

Added some suggestions here: cy-yun#1

This was referenced Oct 7, 2026
Closed
Open

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Hectorhammett Hectorhammett Hectorhammett left review comments
@bshaffer bshaffer Awaiting requested review from bshaffer

Requested changes must be addressed to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@cy-yun @bshaffer @Hectorhammett