chore: add connection property for API tracing

README.md

@@ -50,7 +50,7 @@ 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.41.0')
+implementation platform('com.google.cloud:libraries-bom:26.42.0')
 
 implementation 'com.google.cloud:google-cloud-spanner'
 ```

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;

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

@@ -159,6 +159,7 @@ static class SpannerPoolKey {
     private final boolean useVirtualGrpcTransportThreads;
     private final OpenTelemetry openTelemetry;
     private final Boolean enableExtendedTracing;
+    private final Boolean enableApiTracing;
 
     @VisibleForTesting
     static SpannerPoolKey of(ConnectionOptions options) {
@@ -188,6 +189,7 @@ private SpannerPoolKey(ConnectionOptions options) throws IOException {
       this.useVirtualGrpcTransportThreads = options.isUseVirtualGrpcTransportThreads();
       this.openTelemetry = options.getOpenTelemetry();
       this.enableExtendedTracing = options.isEnableExtendedTracing();
+      this.enableApiTracing = options.isEnableApiTracing();
     }
 
     @Override
@@ -208,7 +210,8 @@ public boolean equals(Object o) {
           && Objects.equals(
               this.useVirtualGrpcTransportThreads, other.useVirtualGrpcTransportThreads)
           && Objects.equals(this.openTelemetry, other.openTelemetry)
-          && Objects.equals(this.enableExtendedTracing, other.enableExtendedTracing);
+          && Objects.equals(this.enableExtendedTracing, other.enableExtendedTracing)
+          && Objects.equals(this.enableApiTracing, other.enableApiTracing);
     }
 
     @Override
@@ -225,7 +228,8 @@ public int hashCode() {
           this.routeToLeader,
           this.useVirtualGrpcTransportThreads,
           this.openTelemetry,
-          this.enableExtendedTracing);
+          this.enableExtendedTracing,
+          this.enableApiTracing);
     }
   }
 
@@ -364,6 +368,9 @@ Spanner createSpanner(SpannerPoolKey key, ConnectionOptions options) {
     if (key.enableExtendedTracing != null) {
       builder.setEnableExtendedTracing(key.enableExtendedTracing);
     }
+    if (key.enableApiTracing != null) {
+      builder.setEnableApiTracing(key.enableApiTracing);
+    }
     if (key.numChannels != null) {
       builder.setNumChannels(key.numChannels);
     }

google-cloud-spanner/src/test/java/com/google/cloud/spanner/connection/ConnectionOptionsTest.java

@@ -1165,4 +1165,29 @@ public void testMaxCommitDelay() {
             .build()
             .getMaxCommitDelay());
   }
+
+  @Test
+  public void testEnableApiTracing() {
+    assertNull(
+        ConnectionOptions.newBuilder()
+            .setUri(
+                "cloudspanner:/projects/test-project-123/instances/test-instance/databases/test-database")
+            .setCredentials(NoCredentials.getInstance())
+            .build()
+            .isEnableApiTracing());
+    assertTrue(
+        ConnectionOptions.newBuilder()
+            .setUri(
+                "cloudspanner:/projects/test-project-123/instances/test-instance/databases/test-database?enableApiTracing=true")
+            .setCredentials(NoCredentials.getInstance())
+            .build()
+            .isEnableApiTracing());
+    assertFalse(
+        ConnectionOptions.newBuilder()
+            .setUri(
+                "cloudspanner:/projects/test-project-123/instances/test-instance/databases/test-database?enableApiTracing=false")
+            .setCredentials(NoCredentials.getInstance())
+            .build()
+            .isEnableApiTracing());
+  }
 }

google-cloud-spanner/src/test/java/com/google/cloud/spanner/connection/SpannerPoolTest.java

@@ -515,6 +515,54 @@ public void testSpannerPoolKeyEquality() {
     assertNotEquals(key4, key5);
   }
 
+  @Test
+  public void testEnableApiTracing() {
+    SpannerPoolKey keyWithoutApiTracingConfig =
+        SpannerPoolKey.of(
+            ConnectionOptions.newBuilder()
+                .setUri("cloudspanner:/projects/p/instances/i/databases/d")
+                .setCredentials(NoCredentials.getInstance())
+                .build());
+    SpannerPoolKey keyWithApiTracingEnabled =
+        SpannerPoolKey.of(
+            ConnectionOptions.newBuilder()
+                .setUri("cloudspanner:/projects/p/instances/i/databases/d?enableApiTracing=true")
+                .setCredentials(NoCredentials.getInstance())
+                .build());
+    SpannerPoolKey keyWithApiTracingDisabled =
+        SpannerPoolKey.of(
+            ConnectionOptions.newBuilder()
+                .setUri("cloudspanner:/projects/p/instances/i/databases/d?enableApiTracing=false")
+                .setCredentials(NoCredentials.getInstance())
+                .build());
+
+    assertNotEquals(keyWithoutApiTracingConfig, keyWithApiTracingEnabled);
+    assertNotEquals(keyWithoutApiTracingConfig, keyWithApiTracingDisabled);
+    assertNotEquals(keyWithApiTracingEnabled, keyWithApiTracingDisabled);
+
+    assertEquals(
+        keyWithApiTracingEnabled,
+        SpannerPoolKey.of(
+            ConnectionOptions.newBuilder()
+                .setUri("cloudspanner:/projects/p/instances/i/databases/d?enableApiTracing=true")
+                .setCredentials(NoCredentials.getInstance())
+                .build()));
+    assertEquals(
+        keyWithApiTracingDisabled,
+        SpannerPoolKey.of(
+            ConnectionOptions.newBuilder()
+                .setUri("cloudspanner:/projects/p/instances/i/databases/d?enableApiTracing=false")
+                .setCredentials(NoCredentials.getInstance())
+                .build()));
+    assertEquals(
+        keyWithoutApiTracingConfig,
+        SpannerPoolKey.of(
+            ConnectionOptions.newBuilder()
+                .setUri("cloudspanner:/projects/p/instances/i/databases/d")
+                .setCredentials(NoCredentials.getInstance())
+                .build()));
+  }
+
   @Test
   public void testOpenTelemetry() {
     SpannerPool pool = createSubjectAndMocks();