Merge branch 'main' of https://github.com/googleapis/java-spanner into e2e-tracing-header

Author: nareshz

README.md

@@ -50,20 +50,20 @@ If you are using Maven without the BOM, add this to your dependencies:
 If you are using Gradle 5.x or later, add this to your dependencies:
 
 ```Groovy
-implementation platform('com.google.cloud:libraries-bom:26.40.0')
+implementation platform('com.google.cloud:libraries-bom:26.42.0')
 
 implementation 'com.google.cloud:google-cloud-spanner'
 ```
 If you are using Gradle without BOM, add this to your dependencies:
 
 ```Groovy
-implementation 'com.google.cloud:google-cloud-spanner:6.68.1'
+implementation 'com.google.cloud:google-cloud-spanner:6.69.0'
 ```
 
 If you are using SBT, add this to your dependencies:
 
 ```Scala
-libraryDependencies += "com.google.cloud" % "google-cloud-spanner" % "6.68.1"
+libraryDependencies += "com.google.cloud" % "google-cloud-spanner" % "6.69.0"
 ```
 <!-- {x-version-update-end} -->
 
@@ -687,7 +687,7 @@ Java is a registered trademark of Oracle and/or its affiliates.
 [kokoro-badge-link-5]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-spanner/java11.html
 [stability-image]: https://img.shields.io/badge/stability-stable-green
 [maven-version-image]: https://img.shields.io/maven-central/v/com.google.cloud/google-cloud-spanner.svg
-[maven-version-link]: https://central.sonatype.com/artifact/com.google.cloud/google-cloud-spanner/6.68.1
+[maven-version-link]: https://central.sonatype.com/artifact/com.google.cloud/google-cloud-spanner/6.69.0
 [authentication]: https://github.com/googleapis/google-cloud-java#authentication
 [auth-scopes]: https://developers.google.com/identity/protocols/oauth2/scopes
 [predefined-iam-roles]: https://cloud.google.com/iam/docs/understanding-roles#predefined_roles

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

@@ -0,0 +1,174 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.spanner;
+
+import com.google.api.core.InternalApi;
+import com.google.api.gax.tracing.ApiTracer;
+import com.google.api.gax.tracing.BaseApiTracer;
+import com.google.api.gax.tracing.MetricsTracer;
+import com.google.common.collect.ImmutableList;
+import java.util.ArrayList;
+import java.util.List;
+import org.threeten.bp.Duration;
+
+@InternalApi
+public class CompositeTracer extends BaseApiTracer {
+  private final List<ApiTracer> children;
+
+  public CompositeTracer(List<ApiTracer> children) {
+    this.children = ImmutableList.copyOf(children);
+  }
+
+  @Override
+  public Scope inScope() {
+    final List<Scope> childScopes = new ArrayList<>(children.size());
+
+    for (ApiTracer child : children) {
+      childScopes.add(child.inScope());
+    }
+
+    return new Scope() {
+      @Override
+      public void close() {
+        for (Scope childScope : childScopes) {
+          childScope.close();
+        }
+      }
+    };
+  }
+
+  @Override
+  public void operationSucceeded() {
+    for (ApiTracer child : children) {
+      child.operationSucceeded();
+    }
+  }
+
+  @Override
+  public void operationCancelled() {
+    for (ApiTracer child : children) {
+      child.operationCancelled();
+    }
+  }
+
+  @Override
+  public void operationFailed(Throwable error) {
+    for (ApiTracer child : children) {
+      child.operationFailed(error);
+    }
+  }
+
+  @Override
+  public void connectionSelected(String id) {
+    for (ApiTracer child : children) {
+      child.connectionSelected(id);
+    }
+  }
+
+  @Override
+  public void attemptStarted(int attemptNumber) {
+    for (ApiTracer child : children) {
+      child.attemptStarted(null, attemptNumber);
+    }
+  }
+
+  @Override
+  public void attemptStarted(Object request, int attemptNumber) {
+    for (ApiTracer child : children) {
+      child.attemptStarted(request, attemptNumber);
+    }
+  }
+
+  @Override
+  public void attemptSucceeded() {
+    for (ApiTracer child : children) {
+      child.attemptSucceeded();
+    }
+  }
+
+  @Override
+  public void attemptCancelled() {
+    for (ApiTracer child : children) {
+      child.attemptCancelled();
+    }
+  }
+
+  @Override
+  public void attemptFailed(Throwable error, Duration delay) {
+    for (ApiTracer child : children) {
+      child.attemptFailed(error, delay);
+    }
+  }
+
+  @Override
+  public void attemptFailedRetriesExhausted(Throwable error) {
+    for (ApiTracer child : children) {
+      child.attemptFailedRetriesExhausted(error);
+    }
+  }
+
+  @Override
+  public void attemptPermanentFailure(Throwable error) {
+    for (ApiTracer child : children) {
+      child.attemptPermanentFailure(error);
+    }
+  }
+
+  @Override
+  public void lroStartFailed(Throwable error) {
+    for (ApiTracer child : children) {
+      child.lroStartFailed(error);
+    }
+  }
+
+  @Override
+  public void lroStartSucceeded() {
+    for (ApiTracer child : children) {
+      child.lroStartSucceeded();
+    }
+  }
+
+  @Override
+  public void responseReceived() {
+    for (ApiTracer child : children) {
+      child.responseReceived();
+    }
+  }
+
+  @Override
+  public void requestSent() {
+    for (ApiTracer child : children) {
+      child.requestSent();
+    }
+  }
+
+  @Override
+  public void batchRequestSent(long elementCount, long requestSize) {
+    for (ApiTracer child : children) {
+      child.batchRequestSent(elementCount, requestSize);
+    }
+  }
+
+  public void addAttributes(String key, String value) {
+    for (ApiTracer child : children) {
+      if (child instanceof MetricsTracer) {
+        MetricsTracer metricsTracer = (MetricsTracer) child;
+        metricsTracer.addAttributes(key, value);
+      }
+    }
+  };
+}

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

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.spanner;
+
+import com.google.api.core.InternalApi;
+import com.google.api.gax.tracing.ApiTracer;
+import com.google.api.gax.tracing.ApiTracerFactory;
+import com.google.api.gax.tracing.BaseApiTracerFactory;
+import com.google.api.gax.tracing.SpanName;
+import com.google.common.collect.ImmutableList;
+import java.util.ArrayList;
+import java.util.List;
+
+@InternalApi
+public class CompositeTracerFactory extends BaseApiTracerFactory {
+
+  private final List<ApiTracerFactory> apiTracerFactories;
+
+  public CompositeTracerFactory(List<ApiTracerFactory> apiTracerFactories) {
+    this.apiTracerFactories = ImmutableList.copyOf(apiTracerFactories);
+  }
+
+  @Override
+  public ApiTracer newTracer(ApiTracer parent, SpanName spanName, OperationType operationType) {
+    List<ApiTracer> children = new ArrayList<>(apiTracerFactories.size());
+
+    for (ApiTracerFactory factory : apiTracerFactories) {
+      children.add(factory.newTracer(parent, spanName, operationType));
+    }
+    return new CompositeTracer(children);
+  }
+}

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

@@ -44,6 +44,11 @@ T getReadContext() {
     try {
       return this.readContextFuture.get();
     } catch (ExecutionException executionException) {
+      // Propagate the underlying exception as a RuntimeException (SpannerException is also a
+      // RuntimeException).
+      if (executionException.getCause() instanceof RuntimeException) {
+        throw (RuntimeException) executionException.getCause();
+      }
       throw SpannerExceptionFactory.asSpannerException(executionException.getCause());
     } catch (InterruptedException interruptedException) {
       throw SpannerExceptionFactory.propagateInterrupt(interruptedException);

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

@@ -72,7 +72,9 @@
 import java.io.IOException;
 import java.net.MalformedURLException;
 import java.net.URL;
+import java.util.ArrayList;
 import java.util.HashMap;
+import java.util.List;
 import java.util.Map;
 import java.util.Map.Entry;
 import java.util.Set;
@@ -1634,8 +1636,12 @@ public OpenTelemetry getOpenTelemetry() {
 
   @Override
   public ApiTracerFactory getApiTracerFactory() {
+    List<ApiTracerFactory> apiTracerFactories = new ArrayList();
     // Prefer any direct ApiTracerFactory that might have been set on the builder.
-    return MoreObjects.firstNonNull(super.getApiTracerFactory(), getDefaultApiTracerFactory());
+    apiTracerFactories.add(
+        MoreObjects.firstNonNull(super.getApiTracerFactory(), getDefaultApiTracerFactory()));
+
+    return new CompositeTracerFactory(apiTracerFactories);
   }
 
   private ApiTracerFactory getDefaultApiTracerFactory() {

google-cloud-spanner/src/main/java/com/google/cloud/spanner/connection/AbstractBaseUnitOfWork.java

@@ -165,6 +165,11 @@ B setSpan(@Nullable Span span) {
     this.span = Preconditions.checkNotNull(builder.span);
   }
 
+  @Override
+  public Span getSpan() {
+    return this.span;
+  }
+
   ApiFuture<Void> asyncEndUnitOfWorkSpan() {
     return this.statementExecutor.submit(this::endUnitOfWorkSpan);
   }

google-cloud-spanner/src/main/java/com/google/cloud/spanner/connection/ConnectionImpl.java

@@ -96,7 +96,6 @@ class ConnectionImpl implements Connection {
   private static final String SINGLE_USE_TRANSACTION = "SingleUseTransaction";
   private static final String READ_ONLY_TRANSACTION = "ReadOnlyTransaction";
   private static final String READ_WRITE_TRANSACTION = "ReadWriteTransaction";
-  private static final String DML_BATCH = "DmlBatch";
   private static final String DDL_BATCH = "DdlBatch";
   private static final String DDL_STATEMENT = "DdlStatement";
 
@@ -1932,7 +1931,8 @@ UnitOfWork createNewUnitOfWork(
               .setStatementTag(statementTag)
               .setExcludeTxnFromChangeStreams(excludeTxnFromChangeStreams)
               .setRpcPriority(rpcPriority)
-              .setSpan(createSpanForUnitOfWork(DML_BATCH))
+              // Use the transaction Span for the DML batch.
+              .setSpan(transactionStack.peek().getSpan())
               .build();
         case DDL_BATCH:
           return DdlBatch.newBuilder()

google-cloud-spanner/src/main/java/com/google/cloud/spanner/connection/ConnectionOptions.java

@@ -199,6 +199,7 @@ public String[] getValidValues() {
   private static final int DEFAULT_MAX_PARTITIONS = 0;
   private static final int DEFAULT_MAX_PARTITIONED_PARALLELISM = 1;
   private static final Boolean DEFAULT_ENABLE_EXTENDED_TRACING = null;
+  private static final Boolean DEFAULT_ENABLE_API_TRACING = null;
 
   private static final String PLAIN_TEXT_PROTOCOL = "http:";
   private static final String HOST_PROTOCOL = "https:";
@@ -280,6 +281,7 @@ public String[] getValidValues() {
       "maxPartitionedParallelism";
 
   public static final String ENABLE_EXTENDED_TRACING_PROPERTY_NAME = "enableExtendedTracing";
+  public static final String ENABLE_API_TRACING_PROPERTY_NAME = "enableApiTracing";
 
   private static final String GUARDED_CONNECTION_PROPERTY_ERROR_MESSAGE =
       "%s can only be used if the system property %s has been set to true. "
@@ -448,7 +450,14 @@ private static String generateGuardedConnectionPropertyError(
                       "Include the SQL string in the OpenTelemetry traces that are generated "
                           + "by this connection. The SQL string is added as the standard OpenTelemetry "
                           + "attribute 'db.statement'.",
-                      DEFAULT_ENABLE_EXTENDED_TRACING))));
+                      DEFAULT_ENABLE_EXTENDED_TRACING),
+                  ConnectionProperty.createBooleanProperty(
+                      ENABLE_API_TRACING_PROPERTY_NAME,
+                      "Add OpenTelemetry traces for each individual RPC call. Enable this "
+                          + "to get a detailed view of each RPC that is being executed by your application, "
+                          + "or if you want to debug potential latency problems caused by RPCs that are "
+                          + "being retried.",
+                      DEFAULT_ENABLE_API_TRACING))));
 
   private static final Set<ConnectionProperty> INTERNAL_PROPERTIES =
       Collections.unmodifiableSet(
@@ -743,6 +752,7 @@ public static Builder newBuilder() {
   private final OpenTelemetry openTelemetry;
   private final String tracingPrefix;
   private final Boolean enableExtendedTracing;
+  private final Boolean enableApiTracing;
   private final List<StatementExecutionInterceptor> statementExecutionInterceptors;
   private final SpannerOptionsConfigurator configurator;
 
@@ -851,6 +861,7 @@ private ConnectionOptions(Builder builder) {
     this.openTelemetry = builder.openTelemetry;
     this.tracingPrefix = builder.tracingPrefix;
     this.enableExtendedTracing = parseEnableExtendedTracing(this.uri);
+    this.enableApiTracing = parseEnableApiTracing(this.uri);
     this.statementExecutionInterceptors =
         Collections.unmodifiableList(builder.statementExecutionInterceptors);
     this.configurator = builder.configurator;
@@ -1251,6 +1262,12 @@ static Boolean parseEnableExtendedTracing(String uri) {
     return value != null ? Boolean.valueOf(value) : DEFAULT_ENABLE_EXTENDED_TRACING;
   }
 
+  @VisibleForTesting
+  static Boolean parseEnableApiTracing(String uri) {
+    String value = parseUriProperty(uri, ENABLE_API_TRACING_PROPERTY_NAME);
+    return value != null ? Boolean.valueOf(value) : DEFAULT_ENABLE_API_TRACING;
+  }
+
   @VisibleForTesting
   static String parseUriProperty(String uri, String property) {
     Pattern pattern = Pattern.compile(String.format("(?is)(?:;|\\?)%s=(.*?)(?:;|$)", property));
@@ -1558,6 +1575,10 @@ Boolean isEnableExtendedTracing() {
     return this.enableExtendedTracing;
   }
 
+  Boolean isEnableApiTracing() {
+    return this.enableApiTracing;
+  }
+
   /** Interceptors that should be executed after each statement */
   List<StatementExecutionInterceptor> getStatementExecutionInterceptors() {
     return statementExecutionInterceptors;