feat(o11y): Introduce rpc.system.name and rpc.method in gRPC

[diegomarquezp]

This PR introduces the rpc.system.name and rpc.method span attributes in gRPC.

To achieve this, all Traced*Callable classes were modified with a constructor overload that accepts an ApiTracerContext instance. Such an instance will be preferred over SpanName when deciding which (also newly introduced) overload of ApiTracerFactory.newTracer() will be called.

The new method in ApiTracerFactory, newTracer(ApiTracer parent, ApiTracerContext tracerContext, OperationType operationType) will by default merge the existing factory's context with the new one and simply create a new SpanName.

However, the logic in SpanTracerFactory will use the context to create the span name directly.

The rpc.system.name and rpc.method properties are obtained from GrpcCallableFactory and stored in ApiTracerContext, which now holds the regexes for parsing client and method names (used when building SpanNames).

[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 introduces significant improvements to the observability framework by enriching tracing contexts with RPC system and method information. It refactors the tracing mechanism to be more flexible and less dependent on specific span naming conventions, allowing for better integration with standardized observability practices. The changes streamline how RPC details are captured and propagated through the tracing system, enhancing the clarity and utility of generated traces.

Highlights

• Enhanced Tracing Context: The ApiTracerContext has been significantly enhanced to include rpc.system.name and rpc.method attributes, along with clientName and methodName. This allows for more granular and standardized observability data in tracing spans.
• Decoupling Tracing from SpanName: The tracing mechanism no longer directly relies on the SpanName object. Instead, ApiTracerFactory and related callable wrappers now receive an ApiTracerFactory that is pre-configured with the necessary context, including RPC system and method details.
• Automated RPC Context Extraction: New static factory methods (fromGrpcMethodName and fromHttpJsonMethodName) have been added to ApiTracerContext to automatically parse full method names (gRPC or HTTP/JSON) and extract the rpcSystem, rpcMethod, clientName, and methodName for tracing.
• Refactored Callable Factories: Both GrpcCallableFactory and HttpJsonCallableFactory have been updated to utilize the new ApiTracerContext for creating tracers, simplifying the tracing setup within these factories and removing redundant logic for extracting method names.

Changelog

• gax-java/gax-grpc/src/main/java/com/google/api/gax/grpc/GrpcCallableFactory.java
  • Removed InternalApi and SpanName related imports.
  • Removed the FULL_METHOD_NAME_REGEX pattern and its usage.
  • Updated various create*Callable methods to use a new getTracerFactory helper method for obtaining ApiTracerFactory instances.
  • Introduced a new private static method getTracerFactory to construct ApiTracerContext from gRPC method descriptors.
• gax-java/gax-httpjson/src/main/java/com/google/api/gax/httpjson/HttpJsonCallableFactory.java
  • Removed InternalApi and SpanName related imports.
  • Removed the FULL_METHOD_NAME_REGEX pattern and its usage.
  • Updated createUnaryCallable to use a new getTracerFactory helper method.
  • Introduced a new private static method getTracerFactory to construct ApiTracerContext from HTTP/JSON method descriptors.
• gax-java/gax/src/main/java/com/google/api/gax/tracing/ApiTracerContext.java
  • Added new fields: rpcSystem, rpcMethod, clientName, and methodName.
  • Updated getAttemptAttributes to include rpc.system.name and rpc.method.
  • Added merge method for combining ApiTracerContext instances.
  • Introduced static factory methods fromGrpcMethodName and fromHttpJsonMethodName for parsing method names.
  • Added corresponding builder methods for the new fields.
• gax-java/gax/src/main/java/com/google/api/gax/tracing/ApiTracerFactory.java
  • Modified the newTracer method signature to remove the SpanName parameter.
• gax-java/gax/src/main/java/com/google/api/gax/tracing/BaseApiTracerFactory.java
  • Updated the newTracer method signature to align with the ApiTracerFactory interface.
• gax-java/gax/src/main/java/com/google/api/gax/tracing/ObservabilityAttributes.java
  • Added new constants RPC_SYSTEM_NAME_ATTRIBUTE and RPC_METHOD_ATTRIBUTE.
• gax-java/gax/src/main/java/com/google/api/gax/tracing/SpanTracerFactory.java
  • Modified the newTracer method signature to remove the SpanName parameter.
  • Updated the attemptSpanName calculation to use apiTracerContext fields.
  • Modified withContext to merge the provided context with the existing apiTracerContext.
• gax-java/gax/src/main/java/com/google/api/gax/tracing/TracedUnaryCallable.java
  • Removed the spanName field and its usage.
  • Updated the constructor and futureCall method to no longer accept or use SpanName.

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 significant and beneficial refactoring to the tracing infrastructure. By replacing the explicit SpanName with a more structured ApiTracerContext carried by ApiTracerFactory, the code becomes more maintainable and extensible. The introduction of rpc.system.name and rpc.method attributes aligns with modern observability practices.

However, there are a couple of points that need attention:

1. Missing Tests (Critical): The PR adds new logic (e.g., in ApiTracerContext) and refactors existing components, but it lacks corresponding unit tests. The repository's contribution guidelines (line 148: Testing: All new logic should be accompanied by tests.) are not being met. Please add tests for the new functionality, especially for the parsing logic in ApiTracerContext.fromGrpcMethodName and ApiTracerContext.fromHttpJsonMethodName, and ensure existing tests are updated to reflect the API changes.

2. Robustness: There's a potential for a NullPointerException in SpanTracerFactory which can be addressed with a defensive check.

Overall, this is a good direction, but the lack of tests is a critical issue that must be addressed before merging.

[sonarqubecloud]

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

Issues
2 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[sonarqubecloud]

Quality Gate failed for 'java_showcase_integration_tests'

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

See analysis details on SonarQube Cloud

[diegomarquezp]

Error:  Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.13.0:testCompile (default-testCompile) on project google-cloud-bigtable: Compilation failure: Compilation failure: 
Error:  /home/runner/work/sdk-platform-java/sdk-platform-java/java-shared-dependencies/target/java-bigtable/google-cloud-bigtable/src/test/java/com/google/cloud/bigtable/data/v2/stub/BigtableUnaryOperationCallableTest.java:[54,30] error: reference to newTracer is ambiguous
Error:    both method newTracer(ApiTracer,SpanName,OperationType) in ApiTracerFactory and method newTracer(ApiTracer,ApiTracerContext,OperationType) in ApiTracerFactory match
Error:  /home/runner/work/sdk-platform-java/sdk-platform-java/java-shared-dependencies/target/java-bigtable/google-cloud-bigtable/src/test/java/com/google/cloud/bigtable/data/v2/stub/SkipTrailersTest.java:[97,22] error: reference to newTracer is ambiguous
Error:    both method newTracer(ApiTracer,SpanName,OperationType) in ApiTracerFactory and method newTracer(ApiTracer,ApiTracerContext,OperationType) in ApiTracerFactory match

We will need mock adjustments downstream.

For example, SkipTrailersTest

when(tracerFactory.newTracer(Mockito.any(), Mockito.any(), Mockito.any())).thenReturn(tracer);

Mockit.any() doesn't clarify whether it's the SpanName argument or the ApiTracerContext argument.