feat: include RequestID in requests and errors #4263

olavloite · 2025-12-12T14:32:28Z

Send a RequestID to Spanner for each request
Make sure that the attempt number of the RequestID is increased if the RPC is retried.
Include the RequestID in every error that is thrown due to an error that is returned by Spanner.

This change removes most of the manual handling of RequestIDs, and instead lets the SpannerRpc implementation and a couple of interceptors handle RequestIDs.

gemini-code-assist · 2025-12-12T14:33:55Z

Summary of Changes

Hello @olavloite, 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 improves the observability and debugging experience for the Spanner client library by integrating a comprehensive RequestID tracking system. This system ensures that every API call to Spanner carries a unique identifier, which is then propagated through retries and included in any resulting error messages. This change allows developers to more easily trace the lifecycle of individual requests and diagnose issues within distributed Spanner operations.

Highlights

Request ID Propagation: Introduced a mechanism to send a unique RequestID with every Spanner API request, enhancing traceability and debugging capabilities.
Retry Attempt Tracking: The RequestID now includes an attempt number that is automatically incremented when an RPC is retried, providing clearer insight into retry behavior.
Error Reporting: All SpannerException instances now include the relevant RequestID in their details, making it easier to correlate errors with specific requests.
Refactored Request ID Handling: The internal handling of RequestID generation and propagation has been refactored, moving RequestIdCreator responsibility to the SpannerRpc layer and simplifying exception constructors.

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 well-executed refactoring to automate the handling of RequestID for Spanner requests. The changes move the responsibility of creating, propagating, and incrementing request IDs from the application logic into a new gRPC interceptor layer. This simplifies the higher-level code, reduces boilerplate, and makes the request ID handling more robust and centralized.

The key changes include:

Introducing RequestIdCreatorImpl for generating request IDs.
Adding RequestIdInterceptor to inject the request ID into gRPC headers and increment attempt numbers on retries.
Modifying SpannerErrorInterceptor to propagate the request ID in error trailers, allowing exceptions to automatically capture it.
Removing manual request ID management from numerous classes, including SpannerException subclasses, AbstractReadContext, TransactionRunnerImpl, and SessionImpl.
Adding a comprehensive new test class, RequestIdMockServerTest, which thoroughly validates the new mechanism.

The code quality is high, and the changes are consistent and logical. This is an excellent improvement to the client library's architecture.

olavloite · 2025-12-12T14:35:05Z

google-cloud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/GapicSpannerRpc.java


            if (operationName == null) {
-              GrpcCallContext context = newCallContext(null, instanceName, initialRequest, method);
+              GrpcCallContext context = newAdminCallContext(instanceName, initialRequest, method);


This isn't directly related, but a small cleanup to prevent each of these methods to invoke newCallContext(null, ...), and instead use a more descriptive method.

olavloite · 2025-12-12T14:39:15Z

...e-cloud-spanner/src/main/java/com/google/cloud/spanner/MultiplexedSessionDatabaseClient.java

  @Override
  public long executePartitionedUpdate(Statement stmt, UpdateOption... options) {
-    return createMultiplexedSessionTransaction(/* singleUse= */ true)
+    return createMultiplexedSessionTransaction(/* singleUse= */ false)


PartitionedDML is not a single-use transaction. It invokes the BeginTransaction RPC and the ExecuteStreamingSql RPC. These two calls should use the same channel.

olavloite · 2025-12-12T14:40:02Z

...-cloud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/SpannerInterceptorProvider.java

    defaultInterceptorList.add(
        new LoggingInterceptor(Logger.getLogger(GapicSpannerRpc.class.getName()), Level.FINER));
    defaultInterceptorList.add(new HeaderInterceptor(new SpannerRpcMetrics(openTelemetry)));
+    defaultInterceptorList.add(new RequestIdInterceptor());


This adds a generic interceptor that adds the RequestID header from a CallOption.

olavloite · 2025-12-12T14:41:05Z

google-cloud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/SpannerErrorInterceptor.java

+                  return;
+                }
                try {
+                  if (headers.containsKey(XGoogSpannerRequestId.REQUEST_ID_HEADER_KEY)) {


This adds the original RequestID in the error if Spanner returns a non-OK status code for an RPC. This ensures that all errors that originate from Spanner contain a RequestID, and those that do not originate from Spanner do not contain a RequestID.

olavloite · 2025-12-12T14:43:46Z

google-cloud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/GapicSpannerRpc.java

      ReadRequest request,
      ResultStreamConsumer consumer,
      @Nullable Map<Option, ?> options,
+      XGoogSpannerRequestId requestId,


The streaming RPCs (StreamingRead, ExecuteStreamingSql) that handle retries of UNAVAILABLE errors manually must pass in a RequestID. This ensures that the same RequestID is used for both the original attempt and any retries that happen. This again ensures that the attempt number is increased for retries.

olavloite · 2025-12-12T14:45:45Z

google-cloud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/GapicSpannerRpc.java

-      context = withRequestId(context, options);
+    int requestIdChannel = convertToRequestIdChannelNumber(affinity);
+    if (requestId == null) {
+      requestId = requestIdCreator.nextRequestId(requestIdChannel);


We generate a RequestID automatically here for all unary RPCs. We can safely do that, as retries are handled internally by Gax. This means that the same RequestID is automatically used during a retry, and the RequestIdInterceptor can just increase the attempt number every time that the RPC is invoked.

olavloite · 2025-12-12T14:48:41Z

google-cloud-spanner/src/main/java/com/google/cloud/spanner/XGoogSpannerRequestId.java

+        XGoogSpannerRequestId.VERSION,
+        XGoogSpannerRequestId.RAND_PROCESS_ID,
+        this.nthClientId,
+        this.nthChannelId < 0 ? "x" : String.valueOf(this.nthChannelId),


ChannelId < 0 is used in tests to indicate 'A channel ID is expected, but it is unknown which it will be'

olavloite · 2025-12-12T14:49:39Z

google-cloud-spanner/src/test/java/com/google/cloud/spanner/DatabaseClientImplTest.java

-        InProcessServerBuilder.forName(uniqueName)
-            // We need to use a real executor for timeouts to occur.
-            .scheduledExecutorService(new ScheduledThreadPoolExecutor(1))
+        NettyServerBuilder.forAddress(address)


This test must use a standard (TCP-based) channel provider, otherwise the interceptors are not added to the client.

- Send a RequestID to Spanner for each request - Make sure that the attempt number of the RequestID is increased if the RPC is retried. - Include the RequestID in every error that is thrown due to an error that is returned by Spanner.

olavloite requested review from a team as code owners December 12, 2025 14:32

product-auto-label bot added size: l Pull request size is large. api: spanner Issues related to the googleapis/java-spanner API. labels Dec 12, 2025

gemini-code-assist bot reviewed Dec 12, 2025

View reviewed changes

olavloite commented Dec 12, 2025

View reviewed changes

feat: include RequestID in requests and errors

0cd7e3a

- Send a RequestID to Spanner for each request - Make sure that the attempt number of the RequestID is increased if the RPC is retried. - Include the RequestID in every error that is thrown due to an error that is returned by Spanner.

olavloite force-pushed the request-id branch from 80217b1 to 0cd7e3a Compare December 12, 2025 15:05

olavloite mentioned this pull request Dec 12, 2025

feat: make grpc-gcp default enabled #4239

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: include RequestID in requests and errors #4263

feat: include RequestID in requests and errors #4263

Uh oh!

olavloite commented Dec 12, 2025 •

edited

Loading

Uh oh!

gemini-code-assist bot commented Dec 12, 2025

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

olavloite Dec 12, 2025

Uh oh!

olavloite Dec 12, 2025

Uh oh!

olavloite Dec 12, 2025

Uh oh!

olavloite Dec 12, 2025

Uh oh!

olavloite Dec 12, 2025

Uh oh!

olavloite Dec 12, 2025

Uh oh!

olavloite Dec 12, 2025

Uh oh!

olavloite Dec 12, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

feat: include RequestID in requests and errors #4263

Are you sure you want to change the base?

feat: include RequestID in requests and errors #4263

Uh oh!

Conversation

olavloite commented Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist bot commented Dec 12, 2025

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!

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!

1 participant

olavloite commented Dec 12, 2025 •

edited

Loading