feat(o11y): Introduce `rpc.system.name` and `rpc.method` in gRPC by diegomarquezp · Pull Request #4121 · googleapis/sdk-platform-java

diegomarquezp · 2026-02-25T21:57:51Z

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 · 2026-02-25T21:58:14Z

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.

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:

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

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

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

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

sonarqubecloud · 2026-03-02T20:17:23Z

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 · 2026-03-02T20:21:10Z

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 · 2026-03-02T20:31:47Z

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.

blakeli0 · 2026-03-03T01:47:32Z

gax-java/gax-grpc/src/main/java/com/google/api/gax/grpc/GrpcCallableFactory.java


    OperationCallable<RequestT, ResponseT, MetadataT> tracedOperationCallable =
        new TracedOperationCallable<>(
-            operationCallable, clientContext.getTracerFactory(), operationSpanName);


Anything related to Operation is LRO, which is OOS for now. We can finalized the method name format for LRO in next quarter.

blakeli0 · 2026-03-03T01:48:29Z

gax-java/gax-grpc/src/main/java/com/google/api/gax/grpc/GrpcCallableFactory.java

            baseCallable,
            clientContext.getTracerFactory(),
-            getSpanName(grpcCallSettings.getMethodDescriptor()),
+            getApiTracerContext(grpcCallSettings.getMethodDescriptor()),


Batching is technically OOS also, but since this is a very low risk change, I think we can take it.

blakeli0 · 2026-03-03T01:52:34Z

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

+    if (transport() == null) {
+      return null;
+    }
+    return transport() == Transport.GRPC ? "grpc" : "http";


Can we use Transport.GRPC.toString()? Or if we still prefer lowercase, we can put grpc/http as label in the enum.

blakeli0 · 2026-03-03T02:05:08Z

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

    this.innerCallable = innerCallable;
    this.tracerFactory = tracerFactory;
    this.spanName = spanName;
+    this.apiTracerContext = null;


Can we create an apiTracerContext from the SpanName so we don't have to do null check below?

blakeli0 · 2026-03-03T02:13:22Z

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

Do we have to make changes in this file and BaseApiTracerFactory? I think the default methods in ApiTracerFactory should not require us to do so?

blakeli0 · 2026-03-03T02:15:30Z

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

+   */
+  default ApiTracer newTracer(
+      ApiTracer parent, ApiTracerContext tracerContext, OperationType operationType) {
+    ApiTracerContext context = getApiTracerContext().merge(tracerContext);


The default implementation is for backward compatibility. I don't think we need to merge because the existing overridden classes don't have an existing ApiTracerContext?

blakeli0 · 2026-03-03T02:28:34Z

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

+  /**
+   * @return the client name part of the span name
+   */
+  public String getClientName() {


Is clientName just serviceName which we should already have it in StubSettings?

blakeli0 · 2026-03-03T02:29:25Z

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

+  }
+
+  private String[] getParsedFullMethodNameParts() {
+    Preconditions.checkState(fullMethodName() != null, "rpcMethod must be set to get SpanName");


to get SpanName does not apply anymore.

blakeli0 · 2026-03-03T02:30:58Z

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

+  }
+
+  /**
+   * @return the method name part of the span name


method name could be used for more than Span, can we use more generic terms instead of span name in the Java docs?

In addition, can we provide an example for each of the public attributes so its easier to understand?

product-auto-label bot added the size: m Pull request size is medium. label Feb 25, 2026

gemini-code-assist bot reviewed Feb 25, 2026

View reviewed changes

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

diegomarquezp added do not merge Indicates a pull request not ready for merge, due to either quality or timing. needs work This is a pull request that needs a little love. wip Work in Progress labels Feb 25, 2026

Base automatically changed from observability/tracing-attr/repo-artifact to main February 26, 2026 19:03

feat: pass whole context to traced callables

e5b927a

diegomarquezp force-pushed the observability/tracing-attr/rpc.method-and-rpc.system branch from b32f09a to e5b927a Compare February 26, 2026 20:13

diegomarquezp added 3 commits February 26, 2026 15:41

fix: provide getter of SpanName with suffix

956ae29

fix: concise logic in http callable factory

dfe6216

chore: expose newTracer method without SpanName

0ee9f4a

product-auto-label bot added size: l Pull request size is large. and removed size: m Pull request size is medium. labels Feb 27, 2026

diegomarquezp added 4 commits February 27, 2026 14:02

test: adapt tests

3cddc1b

test: move span name tests

2880286

fix: remove SpanName out of ApiTracerContext

74f97f6

fix: keep suffix in the context class

418b954

diegomarquezp commented Feb 27, 2026

View reviewed changes

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

diegomarquezp commented Feb 27, 2026

View reviewed changes

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

diegomarquezp added 7 commits March 2, 2026 11:30

fix: revert changes in httpjson

7189841

feat: merge context in factory method

e648a63

test: revert traced callable tests

6b679d5

feat: SpanTracerFactory to implement newTracer with context

6fbcc08

chore: rename rpcMethod to fullMethodName

8b0a403

test: adapt traced callable tests

b45401e

test: adapt showcase it

a49828f

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

test: expand tests of SpanTracerFactory

5ecf1b0

diegomarquezp added 2 commits March 2, 2026 14:59

chore: lint grpc module

82cc227

chore: fix license

d9c4d80

diegomarquezp changed the title ~~chore(o11y): demo of rpc.system.name and rpc.method~~ feat(o11y): Introduce rpc.system.name and rpc.method in gRPC Mar 2, 2026

diegomarquezp removed do not merge Indicates a pull request not ready for merge, due to either quality or timing. needs work This is a pull request that needs a little love. wip Work in Progress labels Mar 2, 2026

diegomarquezp marked this pull request as ready for review March 2, 2026 20:32

blakeli0 reviewed Mar 3, 2026

View reviewed changes

Conversation

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

Uh oh!

Uh oh!

gemini-code-assist bot commented Feb 25, 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!

sonarqubecloud bot commented Mar 2, 2026

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

Uh oh!

sonarqubecloud bot commented Mar 2, 2026

Quality Gate failed for 'java_showcase_integration_tests'

Uh oh!

diegomarquezp commented Mar 2, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

diegomarquezp commented Feb 25, 2026 •

edited

Loading