impl(o11y): introduce `error.type` by diegomarquezp · Pull Request #4148 · googleapis/sdk-platform-java

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

This PR introduces error.type observability attribute, which is obtained from error information (i.e. Throwables).

Key Changes:

Introduction of ErrorTypeUtils, with public surface, that provides a string representation of the possible error types given a Throwable. Tracing classes such as SpanTracer can rely on it to obtain the error.type attribute from such a throwable.
Temporary addition of addAttribute to Span. This is because attemptFailed() and other sibling methods must modify existing Spans. This will be reverted in the future once we "flatten" the SpanTracer vs SpanManager layout.

Logic

The logic is extensively explained in the javadoc of ErrorTypeUtils.extractErrorType(), but in a nutshell it consists of:

Using the ErrorInfo reason as a primary source
Using the server side error code
Using the client side error as a fallback.

While GAX does not have a clear classification for this, we rely on general patterns in the library plus a proposal in feat: add response attribute tracking google-cloud-java#12104 that lays out part of the logic.

Use the exception class name
Simply return INTERNAL

Testing

Added error-related test in ITOtelTracing

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

ldetmer · 2026-03-17T20:46:20Z

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

+    if (isRequestBodyError(error)) {
+      return ErrorType.CLIENT_REQUEST_BODY_ERROR.toString();
+    }
+    if (isClientUnknownError(error)) {


I thought this was the default option, as in there shouldn't be a check here?

So the fallback sequence is "reason", then "server error" then "client error" then "exception name" then "INTERNAL".
This class is not only for "client error" but for the whole the fallback sequence, so we need the flow to check for other cases such as exception name and INTERNAL.

ldetmer

looks good, just one question

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

Conversation

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

Uh oh!

Key Changes:

Logic

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!

ldetmer Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ldetmer left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

diegomarquezp commented Mar 16, 2026 •

edited

Loading

diegomarquezp Mar 17, 2026 •

edited

Loading