feat: Refine tracing telemetry for client-side attributes by diegomarquezp · Pull Request #4148 · googleapis/sdk-platform-java

diegomarquezp · 2026-03-16T20:52:03Z

Description

This PR enhances GAX's distributed tracing telemetry to align with the latest OpenTelemetry conventions by tracking precise client-side exception metrics on spans.

Key Features

status.message: Introduces a new tracing attribute that captures human-readable error messages from failed spans. Utilizes recursive causal chain traversal to identify the exact cause and message dynamically.
exception.type: Introduces exception class tracking using the fully qualified class name in line with standard diagnostic practices.
error.type Refinement: Adjusted client-side error type mapping strategy. We've introduced a clean fallback heuristic utilizing the exception class name for unresolved internal failures without masking errors under arbitrary fallback categories.
Merge Realignment: Syncs up with main following transport attribute and tracing telemetry modifications.

Testing

Validated via OpenTelemetry Mock Span framework modifications inside SpanTracerTest.java.
Updated gapic-showcase integration suite tests inside ITOtelErrorType to seamlessly run with the updated attribution.

gemini-code-assist · 2026-03-16T20:52:31Z

Summary of Changes

Hello, I'm Gemini Code Assist¹! 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 by introducing a new error.type attribute for tracing spans. This attribute provides a standardized, low-cardinality classification of errors, enabling more effective analysis and aggregation of error data. The changes include a robust error type extraction logic that prioritizes specific error reasons and codes, ensuring consistent and meaningful error reporting across different failure modes.

Highlights

New error.type Attribute: Introduced a new error.type attribute to provide standardized, low-cardinality error classification in observability traces.
Error Type Extraction Logic: Implemented a utility function ObservabilityUtils.extractErrorType to determine the appropriate error type based on a priority system (ErrorInfo.reason, server error codes, client-side errors, language-specific exceptions, or internal fallback).
Span Attribute Support: Extended the TraceManager.Span interface and its OpenTelemetry implementation to support adding custom attributes to spans.
Automated Error Type Recording: Modified SpanTracer to automatically record the error.type attribute on failed operation attempts.
Comprehensive Testing: Added comprehensive unit tests for SpanTracer and integration tests in ITOtelTracing to validate the correct extraction and recording of error.type for various error scenarios.

Changelog

gax-java/gax/src/main/java/com/google/api/gax/tracing/ObservabilityAttributes.java
- Added ERROR_TYPE_ATTRIBUTE constant to define the new error type attribute key.
gax-java/gax/src/main/java/com/google/api/gax/tracing/ObservabilityUtils.java
- Added ErrorType enum for classifying client-side network and operational errors.
- Implemented extractErrorType static method to determine a low-cardinality error type string from a Throwable based on a defined priority order.
gax-java/gax/src/main/java/com/google/api/gax/tracing/OpenTelemetryTraceManager.java
- Implemented the addAttribute method in the OtelSpan inner class to allow setting custom attributes on the underlying OpenTelemetry span.
gax-java/gax/src/main/java/com/google/api/gax/tracing/SpanTracer.java
- Overrode attemptCancelled, attemptFailedDuration, attemptFailedRetriesExhausted, and attemptPermanentFailure methods to ensure error handling.
- Introduced a private recordErrorAndEndAttempt method to add the error.type attribute to the span using ObservabilityUtils.extractErrorType before ending the attempt.
gax-java/gax/src/main/java/com/google/api/gax/tracing/TraceManager.java
- Added addAttribute(String key, String value) method to the Span interface, allowing custom attributes to be attached to spans.
gax-java/gax/src/test/java/com/google/api/gax/tracing/SpanTracerTest.java
- Added necessary imports for ApiException, ErrorDetails, StatusCode, ImmutableList, Any, ErrorInfo, ConnectException, and TimeoutException for testing.
- Added numerous new test methods to verify the error.type extraction and recording logic for various error scenarios, including ErrorInfo.reason, gRPC and HTTP server error codes, and different client-side exceptions.
- Defined several private static exception classes (CredentialsException, DecodeException, RedirectException, RequestBodyException, RequestException, UnknownClientException) to facilitate testing of client-side error types.
java-showcase/gapic-showcase/src/test/java/com/google/showcase/v1beta1/it/ITOtelTracing.java
- Added imports for assertThrows, StatusCode.Code, UnavailableException, and Status for integration testing.
- Added testTracing_failedEcho_grpc_recordsErrorType to verify that the error.type attribute is correctly recorded for gRPC failures.
- Added testTracing_failedEcho_httpjson_recordsErrorType to verify that the error.type attribute is correctly recorded for HTTP/JSON failures.

Activity

Pull request created by diegomarquezp.
Initial implementation of error.type attribute for observability.
Added Javadoc for the new error type logic.

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. ↩

gemini-code-assist

Code Review

This pull request introduces a new observability attribute error.type to provide a more specific, low-cardinality classification of errors. The core logic is implemented in ObservabilityUtils.extractErrorType, which determines the error type based on a clear priority: ErrorInfo.reason, server error codes, specific client-side exceptions, and then fallbacks. The changes are well-supported by comprehensive unit tests in SpanTracerTest and integration tests in ITOtelTracing for both gRPC and HTTP/JSON transports, which is great to see.

My review includes one suggestion for a minor code simplification. Overall, this is a solid implementation.

gax-java/gax/src/main/java/com/google/api/gax/tracing/ObservabilityUtils.java

diegomarquezp · 2026-03-17T19:07:47Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces a new observability attribute, error.type, to provide a low-cardinality classification of errors. The core logic is implemented in the new ErrorTypeUtil class, which extracts the error type based on a priority list, including ErrorInfo.reason, server status codes, and various client-side error categories. The changes are well-tested with both unit and integration tests.

My main feedback is regarding the implementation of client-side error detection in ErrorTypeUtil. Several checks rely on string matching on exception class names or messages (e.g., using String.contains()), which is fragile and can lead to incorrect error classification. I've left specific comments with suggestions to improve the robustness of these checks.

gemini-code-assist · 2026-03-17T19:11:52Z

gax-java/gax/src/main/java/com/google/api/gax/tracing/ErrorTypeUtil.java

+  private static boolean isClientRedirectError(Throwable e) {
+    return e.getMessage() != null && e.getMessage().contains("redirect");
+  }


Relying on the content of an exception message with e.getMessage().contains("redirect") is highly fragile. Exception messages are not a stable API; they can be changed, might not be present, or could be localized, which would break this logic.

It would be much more robust to check for a specific exception type that indicates a redirect error. If no such standard exception exists, this approach has a high risk of being unreliable and should be documented as such.

There are no redirect-specific exceptions in gax. This is only a heuristic to comply with the higher level effort.

gemini-code-assist · 2026-03-17T19:11:52Z

gax-java/gax/src/main/java/com/google/api/gax/tracing/ErrorTypeUtil.java

+  private static boolean isClientUnknownError(Throwable e) {
+    return e.getClass().getName().toLowerCase().contains("unknown");
+  }


Matching unknown in a class name is very broad and risky. It could lead to misclassifying exceptions. For example, an exception from another library with unknown in its name would be incorrectly categorized as CLIENT_UNKNOWN_ERROR.

Given that UnknownHostException is already handled by isClientConnectionError, this check seems too generic. Please consider making this check more specific to the intended exception types or removing it if it's a speculative catch-all.

Agreed we don't have a reliable heuristic that also prevents external code from being caught here. In favor of the current approach, this is the last case to be handled.
One alternative: do not handle CLIENT_UNKNOWN_ERROR.

gax-java/gax/src/main/java/com/google/api/gax/tracing/ErrorTypeUtil.java

sonarqubecloud · 2026-03-17T20:07:00Z

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

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

sonarqubecloud · 2026-03-17T20:11:29Z

Quality Gate failed for 'java_showcase_integration_tests'

Failed conditions
31.6% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

gax-java/gax/src/main/java/com/google/api/gax/tracing/ErrorTypeUtil.java

ldetmer

looks good, just one question

- Removed heuristic exception mappings for CLIENT_REDIRECT_ERROR and CLIENT_UNKNOWN_ERROR to fall back to simple class name - Refined mapping for CLIENT_AUTHENTICATION_ERROR by removing FileNotFoundException - Added unmapped placeholders to ErrorType enum - Updated unit and integration tests to verify new fallback mechanisms

…ry spans Added recursive logic to trace the final underlying exception message and updated relevant telemetry tests to test iteration logic as requested by client.

…-attr/error.type # Conflicts: # gax-java/gax/src/main/java/com/google/api/gax/rpc/ResourceNameExtractor.java # gax-java/gax/src/main/java/com/google/api/gax/tracing/ObservabilityAttributes.java # gax-java/gax/src/main/java/com/google/api/gax/tracing/OpenTelemetryTraceManager.java # gax-java/gax/src/main/java/com/google/api/gax/tracing/SpanTracer.java # gax-java/gax/src/test/java/com/google/api/gax/tracing/SpanTracerTest.java

diegomarquezp added 2 commits March 16, 2026 16:35

impl(o11y): introduce error.type

ee42bf1

docs: add javadoc for error type logic

4269ccd

product-auto-label bot added the size: l Pull request size is large. label Mar 16, 2026

gemini-code-assist bot reviewed Mar 16, 2026

View reviewed changes

gax-java/gax/src/main/java/com/google/api/gax/tracing/ObservabilityUtils.java Outdated Show resolved Hide resolved

diegomarquezp added 6 commits March 17, 2026 13:27

fix: reduce code complexity

e63af7f

chore: add comments

b215900

refactor: put error type logic in new class

bfcad8b

fix: handle request body and unknown error

d3cd69d

fix: improve handling for INTERNAL

f38a66d

docs: add javadoc for private methods

efbe7ba

gemini-code-assist bot reviewed Mar 17, 2026

View reviewed changes

fix: use recursive exception logic

75fe9ca

diegomarquezp changed the title ~~impl(o11y): [wip] introduce error.type'~~ impl(o11y): [wip] introduce error.type Mar 17, 2026

diegomarquezp changed the title ~~impl(o11y): [wip] introduce error.type~~ impl(o11y): introduce error.type Mar 17, 2026

diegomarquezp marked this pull request as ready for review March 17, 2026 20:02

ldetmer reviewed Mar 17, 2026

View reviewed changes

gax-java/gax/src/main/java/com/google/api/gax/tracing/ErrorTypeUtil.java Outdated Show resolved Hide resolved

ldetmer reviewed Mar 17, 2026

View reviewed changes

diegomarquezp marked this pull request as draft March 18, 2026 14:55

diegomarquezp added 4 commits March 18, 2026 16:18

fix: remove unused exceptions

f746253

test: emulate server behavior

9b8c080

test: add ITs for ErrorType

56986fb

test: use one test per exception

fa5b594

product-auto-label bot added size: xl Pull request size is extra large. and removed size: l Pull request size is large. labels Mar 19, 2026

diegomarquezp added 2 commits March 24, 2026 10:41

feat: Add status.message and exception.type attributes to OpenTelemet…

9313dc1

…ry spans Added recursive logic to trace the final underlying exception message and updated relevant telemetry tests to test iteration logic as requested by client.

diegomarquezp changed the title ~~impl(o11y): introduce error.type~~ impl(o11y): track additional exception attributes (error.type, exception.type, status.message) Mar 24, 2026

diegomarquezp and others added 2 commits March 24, 2026 14:36

chore: generate libraries at Tue Mar 24 18:41:13 UTC 2026

6bc03e5

diegomarquezp changed the title ~~impl(o11y): track additional exception attributes (error.type, exception.type, status.message)~~ feat: Refine tracing telemetry for client-side attributes Mar 24, 2026

diegomarquezp closed this Mar 24, 2026

Conversation

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

Uh oh!

Description

Key Features

Testing

Uh oh!

gemini-code-assist bot commented Mar 16, 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!

diegomarquezp commented Mar 17, 2026

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

diegomarquezp Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

diegomarquezp Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sonarqubecloud bot commented Mar 17, 2026

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

Uh oh!

sonarqubecloud bot commented Mar 17, 2026

Quality Gate failed for 'java_showcase_integration_tests'

Uh oh!

Uh oh!

ldetmer left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

diegomarquezp commented Mar 16, 2026 •

edited

Loading