chore: [wip] tracing implementation POC

[diegomarquezp]

No description provided.

[gemini-code-assist]

Summary of Changes

Hello @diegomarquezp, 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 lays the groundwork for integrating OpenTelemetry tracing into the gax-java library. It establishes a robust framework for capturing and managing distributed traces for API operations, including individual retry attempts, thereby significantly enhancing the observability of client-side interactions. This initial implementation provides the necessary components to start instrumenting and monitoring the performance and behavior of API calls within a distributed environment.

Highlights

• OpenTelemetry Integration: The core gax-java library now includes foundational support for OpenTelemetry, enabling distributed tracing for API calls.
• New Tracing Abstractions: Introduced a TracingRecorder interface and its OpenTelemetryTracingRecorder implementation to manage the lifecycle of OpenTelemetry spans, including starting, ending, and recording errors.
• Granular Span Management: The OpenTelemetryTracingTracer now creates distinct spans for the overall API operation and for each individual retry attempt, providing detailed visibility into the execution flow and potential retries.
• Configurable Trace Attributes: The ApiTracerFactory has been extended with a withAttributes method, allowing custom attributes to be added to traces at both the operation and attempt levels for enhanced context.
• Comprehensive Testing: New unit tests for OpenTelemetryTracingRecorder, OpenTelemetryTracingTracer, and OpenTelemetryTracingTracerFactory, along with an integration test in java-showcase, ensure the correct functionality and integration of the tracing implementation.

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.

Footnotes

1. 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 proof-of-concept for OpenTelemetry-based tracing in gax-java. The changes include new interfaces for tracing (TracingRecorder, SpanHandle), OpenTelemetry implementations for these interfaces, and integration into the client lifecycle via a new ApiTracerFactory. The overall approach is sound and lays a good foundation.

My review includes a few key points:

• A high-level design suggestion to make the attribute system more flexible by not limiting it to string values. This is crucial for capturing rich, typed trace data.
• A refactoring suggestion to reduce code duplication in the new tracer implementation.
• Several improvements for the integration tests to make them more robust and to address commented-out code that indicates potential issues.

The changes are a good start for this feature.

[gemini-code-assist]

The use of String for attribute values throughout this new tracing API (in startSpan and SpanHandle.setAttribute) is overly restrictive. Tracing attributes are often numeric or boolean, and converting them to strings loses important type information, hindering analysis in tracing backends (e.g., attemptNumber should be an integer).

To make this API more powerful and aligned with OpenTelemetry, I recommend changing attribute values from String to a more flexible type. Some options:

1. Use io.opentelemetry.api.common.Attributes: This is the most idiomatic OTel approach.
2. Use Map<String, Object>: A more generic approach if you want to avoid a hard dependency on the OTel Attributes class in the interface.
3. Overload setAttribute: For SpanHandle, you could add overloads for common types (long, double, boolean).

This change would need to be propagated through ApiTracerFactory, TracingRecorder, and OpenTelemetryTracingTracer.

[diegomarquezp]

This is true and a pending task: Otel SemConv specifies other types such as int

[gemini-code-assist]

The methods attemptFailedDuration, attemptFailedRetriesExhausted, and attemptPermanentFailure contain identical logic for recording an error on the attempt span and ending it. This duplication can be removed by extracting the logic into a private helper method.

For example:

private void failAttempt(Throwable error) {
  if (attemptHandle != null) {
    attemptHandle.recordError(error);
  }
  endAttempt();
}

Then, each of the attemptFailed... methods can simply call failAttempt(error).

  @Override
  public void attemptFailedDuration(Throwable error, java.time.Duration delay) {
    failAttempt(error);
  }

  @Override
  public void attemptFailedRetriesExhausted(Throwable error) {
    failAttempt(error);
  }

  @Override
  public void attemptPermanentFailure(Throwable error) {
    failAttempt(error);
  }

  private void failAttempt(Throwable error) {
    if (attemptHandle != null) {
      attemptHandle.recordError(error);
    }
    endAttempt();
  }

[gemini-code-assist]

This block of code for verifying the operation span is commented out, which suggests it might not be working as expected. As this is a work-in-progress, it's understandable, but commented-out tests should be avoided in the final version. Could you please either fix the underlying issue so these assertions can be enabled, or remove the commented-out code if it's no longer relevant?

[gemini-code-assist]

This assertion is not using the Truth API idiomatically and is brittle.

1. The expression spans.size() == 10 evaluates to a boolean. You are essentially doing assertThat(true). The idiomatic way is assertThat(spans).hasSize(10);.
2. Asserting a hardcoded number of retries makes the test fragile to changes in retry configuration.

Since you already verify that spans are not empty and all have an error status, consider if this exact size check is necessary. If so, please update to the idiomatic Truth syntax and fix the typo in 'retires'.

Suggested change

	assertThat(spans.size() == 10); // 10 retires
	assertThat(spans).hasSize(10); // 10 retries

[gemini-code-assist]

Similar to the other test, the verification for the operation span is commented out. Please either fix the functionality to allow this to be tested or remove the commented code before merging.

[diegomarquezp]

This logic would likely be better in the tracer factory constructor.

[sonarqubecloud]

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

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

See analysis details on SonarQube Cloud

[sonarqubecloud]

Quality Gate passed for 'java_showcase_integration_tests'

Issues
6 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud