feat(observability): introduce minimal tracing implementation by diegomarquezp · Pull Request #4105 · googleapis/sdk-platform-java · GitHub

Summary

This PR introduces a new tracing mechanism in GAX that allows recording traces using OpenTelemetry. It provides a way of recording spans and attributes, following the existing ApiTracer class pattern with a few tracing-specific additions. The implementation is meant to be extensible to support other implementations.

New Classes

TraceManager: An interface for managing spans and attributes; can be implemented by observability frameworks.
OpenTelemetryTraceManager: An implementation of TraceManager that uses the OpenTelemetry API.
AppCentricTracer: An ApiTracer implementation that delegates span management to a TraceManager.
AppCentricTracerFactory: A factory for creating AppCentricTracer instances.
ApiTracerContext: A context object that carries information (like EndpointContext's server address property) used to infer common attributes for all tracers.
Span: A handle returned by TraceManager to manage the lifecycle of a specific span (ending it, recording errors, or setting attributes).

Approach

Connecting Tracer with Manager

The implementation aims to decouple AppCentricTracer from TraceManager. When a tracer starts an operation or an attempt, it requests a Span from the recorder. This handle allows the tracer to update the span (e.g., adding attributes or recording errors) to keep AppCentricTracer separated from specific recorder implementations (like OpenTelemetry's Span object).

Attribute Inference via ApiTracerContext

To provide a source of Span Attributes that are common to all operations, we introduced ApiTracerContext. This context is passed to ApiTracerFactory and contains information such as serverAddress (provided by EndpointContext). It is operated by ClientContext.
Initially, only serverAddress is contained in this class and it's meant to obtain the server.address attribute.
The class is ultimately operated by AppCentricTracer to extract the necessary attributes.

Integration Tests

A new integration test, ITOtelTracing, was added to the java-showcase module:

It validates that the expected spans (operation and attempt spans) are recorded with the correct names, parent-child relationships, and attributes (including server.address and gcp.client.language).

Note on java-bigtable downstream check

Since SkipTrailersTest mocks the tracer factory, the EndpointContext call to apiTracerFactory.withContext() returns a null factory, causing a null pointer exception when building the client context.
We expect the test to be adjusted with this change with the next release.

Confirmation in Cloud Trace

…-tracing-impl

This reverts commit b7b9e31.

…-tracing-impl

Summary of Changes

Hello @diegomarquezp, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the observability capabilities of GAX by integrating a robust tracing system based on OpenTelemetry. The design emphasizes extensibility and clear separation of concerns, allowing GAX to record detailed RPC lifecycle events as spans and attributes. It introduces a mechanism to automatically enrich these traces with contextual information, providing deeper insights into client-server interactions.

Highlights

OpenTelemetry Integration: Introduces a new tracing mechanism in GAX that records traces using OpenTelemetry, providing an extensible way to monitor RPC lifecycles.
New Tracing Abstractions: Defines core interfaces ('TracingRecorder', 'SpanHandle') and implementations ('OpenTelemetryTracingRecorder', 'TracingTracer', 'TracingTracerFactory') to decouple tracing logic from specific observability frameworks.
Context-Based Attribute Inference: Implements 'ApiTracerContext' to carry information (like 'EndpointContext') for inferring common span attributes, such as 'server.address' and 'gcp.client.language'.
Comprehensive Testing: Adds new unit tests for the tracing components and integration tests ('ITOtelTracing') in 'java-showcase' to validate span recording, relationships, and attribute propagation across gRPC and HTTP/JSON clients.

Changelog

gax-java/gax/src/main/java/com/google/api/gax/rpc/ClientContext.java
- Integrated 'ApiTracerContext' to pass endpoint information to the 'ApiTracerFactory' for attribute inference.
gax-java/gax/src/main/java/com/google/api/gax/rpc/EndpointContext.java
- Added 'resolvedServerAddress()' method and logic to extract the server address from the resolved endpoint string.
gax-java/gax/src/main/java/com/google/api/gax/tracing/ApiTracerContext.java
- New class: Introduced 'ApiTracerContext' to hold common attributes for 'ApiTracer' instances, initially containing 'EndpointContext'.
gax-java/gax/src/main/java/com/google/api/gax/tracing/ApiTracerFactory.java
- Added a default 'withContext' method to allow 'ApiTracerFactory' implementations to incorporate 'ApiTracerContext' for attribute generation.
gax-java/gax/src/main/java/com/google/api/gax/tracing/OpenTelemetryTracingRecorder.java
- New class: Implemented 'TracingRecorder' using the OpenTelemetry API for creating, managing, and ending spans, including setting attributes and recording errors.
gax-java/gax/src/main/java/com/google/api/gax/tracing/TracingRecorder.java
- New interface: Defined 'TracingRecorder' and 'SpanHandle' to abstract span recording operations and lifecycle management.
gax-java/gax/src/main/java/com/google/api/gax/tracing/TracingTracer.java
- New class: Implemented 'ApiTracer' to use 'TracingRecorder' for span management, handling operation and attempt spans, and applying default and inferred attributes.
gax-java/gax/src/main/java/com/google/api/gax/tracing/TracingTracerFactory.java
- New class: Implemented 'ApiTracerFactory' to construct 'TracingTracer' instances, propagating 'TracingRecorder' and handling context-based attribute injection.
gax-java/gax/src/test/java/com/google/api/gax/rpc/EndpointContextTest.java
- Added a test to verify the correct parsing and resolution of server addresses from various endpoint formats.
gax-java/gax/src/test/java/com/google/api/gax/tracing/OpenTelemetryTracingRecorderTest.java
- New unit tests for 'OpenTelemetryTracingRecorder' covering span creation, kind assignment, attribute setting, error recording, and OpenTelemetry context management.
gax-java/gax/src/test/java/com/google/api/gax/tracing/TracingTracerFactoryTest.java
- New unit tests for 'TracingTracerFactory' validating tracer instantiation, attribute propagation, and 'ApiTracerContext' integration.
gax-java/gax/src/test/java/com/google/api/gax/tracing/TracingTracerTest.java
- New unit tests for 'TracingTracer' ensuring correct span lifecycle management for operations and attempts, and attribute handling.
java-showcase/gapic-showcase/src/test/java/com/google/showcase/v1beta1/it/ITOtelTracing.java
- New integration tests ('ITOtelTracing') to verify end-to-end OpenTelemetry tracing for gRPC and HTTP/JSON clients, including span naming, hierarchy, and attribute correctness.

Activity

This pull request introduces a new feature and includes several new files and tests. There is no specific human activity (comments, reviews, or progress updates) recorded in the provided context.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

Code Review

This pull request introduces a new OpenTelemetry-based tracing system into GAX. Key changes include adding ApiTracerContext to provide endpoint information to tracers, enhancing EndpointContext to extract and store server addresses, and implementing TracingRecorder, TracingTracer, and TracingTracerFactory to integrate OpenTelemetry for operation and attempt spans. Review comments highlight the need to address thread-safety in TracingTracer by using ConcurrentHashMap for attributes, improve the robustness of EndpointContext's server address parsing using java.net.URL, remove a potentially problematic default implementation in TracingRecorder to enforce explicit parent span handling, standardize span naming conventions in TracingTracerFactory to align with OpenTelemetry, and correct the copyright year across several new files.

- Rename SpanHandle to GaxSpan - Simplify adding op and attempt attributes - Use HashMap instead of ConcurrentHashMap - Remove error handling (for now)

…ivate

/gemini review

Code Review

This pull request introduces a new tracing mechanism based on OpenTelemetry, which is a great addition for observability. However, a security concern has been identified regarding how server addresses are parsed for tracing attributes. The current implementation may leak sensitive information (such as credentials or tokens) from the endpoint URL into the tracing system if the URL contains userinfo, paths, or query parameters. A suggestion has been provided to improve the parsing logic to strip these sensitive components. Additionally, feedback has been provided to improve consistency, specifically regarding span naming conventions across different span types and enhancing integration tests for consistent attribute verification across different transport protocols.

0

Quality Gate passed for 'gapic-generator-java-root'

Issues
5 New issues
0 Accepted issues

Measures
0 Security Hotspots
94.9% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

Quality Gate passed for 'java_showcase_integration_tests'

Issues
5 New issues
0 Accepted issues

Measures
0 Security Hotspots
89.7% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

LGTM. Let's rename the AppCentric classes as a quick follow up.

🤖 I have created a release *beep* *boop* --- <details><summary>2.67.0</summary> ## [2.67.0](v2.66.1...v2.67.0) (2026-02-18) ### Features * **observability:** introduce minimal tracing implementation ([#4105](#4105)) ([e4e5e89](e4e5e89)) ### Dependencies * Upgrade Google-Auth-Library to v1.43.0 ([#4114](#4114)) ([825298b](825298b)) * Upgrade grpc to 1.76.3 ([#4106](#4106)) ([c6555f5](c6555f5)) </details> --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>

🤖 I have created a release *beep* *boop* --- <details><summary>2.67.0</summary> ## [2.67.0](googleapis/sdk-platform-java@v2.66.1...v2.67.0) (2026-02-18) ### Features * **observability:** introduce minimal tracing implementation ([#4105](googleapis/sdk-platform-java#4105)) ([0ef5c4c](googleapis/sdk-platform-java@0ef5c4c)) ### Dependencies * Upgrade Google-Auth-Library to v1.43.0 ([#4114](googleapis/sdk-platform-java#4114)) ([4a34266](googleapis/sdk-platform-java@4a34266)) * Upgrade grpc to 1.76.3 ([#4106](googleapis/sdk-platform-java#4106)) ([a5dc992](googleapis/sdk-platform-java@a5dc992)) </details> --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>

diegomarquezp added 10 commits February 4, 2026 14:34

feat: introduce minimal implementation of OTel tracing

7082247

chore: avoid new public methods

bfe6a6d

feat: add api tracer context

ea6cb18

Merge remote-tracking branch 'origin/main' into observability/initial…

97bec08

…-tracing-impl

chore: concise comment

097f701

fix: use internal span kind for operations

f547e5a

chore: remove unnecessary inScope implementation

b7b9e31

Revert "chore: remove unnecessary inScope implementation"

556c84c

This reverts commit b7b9e31.

test: add test for inScope()

0359b7d

Merge remote-tracking branch 'origin/main' into observability/initial…

402cb89

…-tracing-impl

product-auto-label Bot added the size: xl Pull request size is extra large. label Feb 5, 2026

gemini-code-assist Bot reviewed Feb 5, 2026

View reviewed changes

diegomarquezp added 6 commits February 5, 2026 15:45

chore: use suggested server address resolution impl

420278b

fix: use concurrent hash map

6de9fb6

chore: remove default impl for startSpan with parent

a61dacf

chore: add opentelemery-context to tests

b000d52

test: increase coverage for TracingTracerTest

9ce0c34

deps: include opentelemetry context in gax

9c6c737

diegomarquezp marked this pull request as ready for review February 5, 2026 23:54

blakeli0 reviewed Feb 6, 2026

View reviewed changes

Comment thread gax-java/gax/src/main/java/com/google/api/gax/tracing/TracingRecorder.java Outdated

blakeli0 reviewed Feb 6, 2026

View reviewed changes

Comment thread gax-java/gax/src/main/java/com/google/api/gax/tracing/TracingRecorder.java Outdated

blakeli0 reviewed Feb 6, 2026

View reviewed changes

Comment thread gax-java/gax/src/main/java/com/google/api/gax/rpc/ClientContext.java

blakeli0 reviewed Feb 6, 2026

View reviewed changes

Comment thread gax-java/gax/src/main/java/com/google/api/gax/tracing/OpenTelemetryTracingRecorder.java Outdated

diegomarquezp added 4 commits February 9, 2026 12:00

chore: simplify and remove error handling

e77de58

chore: review refactor

8f07f61

- Rename SpanHandle to GaxSpan - Simplify adding op and attempt attributes - Use HashMap instead of ConcurrentHashMap - Remove error handling (for now)

chore: make TracingTracerFactory(recorder, opAtts, atAtts) package pr…

2cfcd68

…ivate

chore: remove unnecessary inScope

2415c6b

product-auto-label Bot added the size: l Pull request size is large. label Feb 10, 2026

gemini-code-assist Bot reviewed Feb 10, 2026

View reviewed changes

chore: add language tests

e873904

blakeli0 reviewed Feb 10, 2026

View reviewed changes

Comment thread gax-java/gax/src/main/java/com/google/api/gax/rpc/EndpointContext.java

blakeli0 reviewed Feb 10, 2026

View reviewed changes

Comment thread gax-java/gax/src/main/java/com/google/api/gax/tracing/AppCentricTracer.java Outdated

chore: AppCentricTracer to implement interface

68943b0

blakeli0 reviewed Feb 12, 2026

View reviewed changes

Comment thread gax-java/gax/src/main/java/com/google/api/gax/tracing/AppCentricTracer.java Outdated

Comment thread gax-java/gax/src/main/java/com/google/api/gax/tracing/AppCentricTracer.java

Comment thread gax-java/gax/src/main/java/com/google/api/gax/tracing/AppCentricTracer.java Outdated

diegomarquezp added 2 commits February 12, 2026 14:57

chore: revert operation implementation

cd4d4d0

chore: extract common span attributes to separate class

5b76e40

diegomarquezp commented Feb 12, 2026

View reviewed changes

Comment thread gax-java/gax/src/main/java/com/google/api/gax/tracing/AppCentricTracer.java

diegomarquezp added 2 commits February 12, 2026 15:36

chore: remove unused var

c783d68

chore: restore context dep

3e06b39

blakeli0 reviewed Feb 13, 2026

View reviewed changes

diegomarquezp added 7 commits February 13, 2026 15:25

chore: process attributes in context and tracer classes

40a97a5

chore: rename to GaxSpan

5b43fa5

chore: use fq name for otel tracer

ed4af8e

chore: add otel context to maven deps

3bfd1ce

chore: rename TraceRecorder to TraceManager and GaxSpan to Span

5382d78

chore: remove attrs from factory

4ece157

chore: adjust javadoc in TraceManager

fb57471

product-auto-label Bot added size: l Pull request size is large. and removed size: xl Pull request size is extra large. labels Feb 13, 2026

blakeli0 approved these changes Feb 14, 2026

View reviewed changes

diegomarquezp merged commit e4e5e89 into main Feb 17, 2026
59 of 61 checks passed

diegomarquezp deleted the observability/initial-tracing-impl branch February 17, 2026 17:01

release-please Bot mentioned this pull request Feb 17, 2026

chore(main): release 2.67.0 #4107

Merged

feat(observability): introduce minimal tracing implementation by diegomarquezp · Pull Request #4105 · googleapis/sdk-platform-java · GitHub

Uh oh!

feat(observability): introduce minimal tracing implementation - #4105

feat(observability): introduce minimal tracing implementation#4105diegomarquezp merged 42 commits intomaingoogleapis/sdk-platform-java:mainfrom observability/initial-tracing-implgoogleapis/sdk-platform-java:observability/initial-tracing-implCopy head branch name to clipboard

Conversation

diegomarquezp commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

New Classes

Approach

Connecting Tracer with Manager

Attribute Inference via ApiTracerContext

Integration Tests

Note on java-bigtable downstream check

Confirmation in Cloud Trace

Uh oh!

gemini-code-assist Bot commented Feb 5, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

diegomarquezp commented Feb 10, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

blakeli0 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sonarqubecloud Bot commented Feb 13, 2026

Quality Gate passed for 'gapic-generator-java-root'

Uh oh!

sonarqubecloud Bot commented Feb 13, 2026

Quality Gate passed for 'java_showcase_integration_tests'

Uh oh!

blakeli0 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

feat(observability): introduce minimal tracing implementation#4105
diegomarquezp merged 42 commits into
mainfrom
observability/initial-tracing-impl

diegomarquezp commented Feb 5, 2026 •
edited
Loading