chore: add support for OpenTelemetry metrics to Connection API

Author: hengfengli

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

@@ -39,6 +39,8 @@
 import com.google.common.base.Strings;
 import com.google.common.collect.Sets;
 import com.google.spanner.v1.ExecuteSqlRequest.QueryOptions;
+import io.opentelemetry.api.GlobalOpenTelemetry;
+import io.opentelemetry.api.OpenTelemetry;
 import java.io.IOException;
 import java.lang.reflect.Constructor;
 import java.lang.reflect.InvocationTargetException;
@@ -54,6 +56,7 @@
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 import java.util.stream.Stream;
+import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
 /**
@@ -169,6 +172,7 @@ public String[] getValidValues() {
   static final boolean DEFAULT_RETRY_ABORTS_INTERNALLY = true;
   static final boolean DEFAULT_USE_VIRTUAL_THREADS = false;
   static final boolean DEFAULT_USE_VIRTUAL_GRPC_TRANSPORT_THREADS = false;
+  static final boolean DEFAULT_ENABLE_OPENTELEMETRY_METRICS = false;
   private static final String DEFAULT_CREDENTIALS = null;
   private static final String DEFAULT_OAUTH_TOKEN = null;
   private static final String DEFAULT_MIN_SESSIONS = null;
@@ -211,6 +215,9 @@ public String[] getValidValues() {
   /** Name of the property to enable/disable virtual threads for gRPC transport. */
   public static final String USE_VIRTUAL_GRPC_TRANSPORT_THREADS_PROPERTY_NAME =
       "useVirtualGrpcTransportThreads";
+  /** Name of the property to enable/disable OpenTelemtry metrics. */
+  public static final String ENABLE_OPENTELEMETRY_METRICS_PROPERTY_NAME =
+      "enableOpenTelemetryMetrics";
   /** Name of the 'credentials' connection property. */
   public static final String CREDENTIALS_PROPERTY_NAME = "credentials";
   /** Name of the 'encodedCredentials' connection property. */
@@ -310,6 +317,10 @@ private static String generateGuardedConnectionPropertyError(
                       "Use a virtual thread instead of a platform thread for the gRPC executor (true/false). "
                           + "This option only has any effect if the application is running on Java 21 or higher. In all other cases, the option is ignored.",
                       DEFAULT_USE_VIRTUAL_GRPC_TRANSPORT_THREADS),
+                  ConnectionProperty.createBooleanProperty(
+                      ENABLE_OPENTELEMETRY_METRICS_PROPERTY_NAME,
+                      "Enable OpenTelemetry metrics in the client library (true/false). ",
+                      DEFAULT_ENABLE_OPENTELEMETRY_METRICS),
                   ConnectionProperty.createStringProperty(
                       CREDENTIALS_PROPERTY_NAME,
                       "The location of the credentials file to use for this connection. If neither this property or encoded credentials are set, the connection will use the default Google Cloud credentials for the runtime environment."),
@@ -484,6 +495,7 @@ public static class Builder {
     private List<StatementExecutionInterceptor> statementExecutionInterceptors =
         Collections.emptyList();
     private SpannerOptionsConfigurator configurator;
+    private OpenTelemetry openTelemetry;
 
     private Builder() {}
 
@@ -633,6 +645,11 @@ Builder setCredentials(Credentials credentials) {
       return this;
     }
 
+    public Builder setOpenTelemetry(OpenTelemetry openTelemetry) {
+      this.openTelemetry = openTelemetry;
+      return this;
+    }
+
     /** @return the {@link ConnectionOptions} */
     public ConnectionOptions build() {
       Preconditions.checkState(this.uri != null, "Connection URI is required");
@@ -691,6 +708,8 @@ public static Builder newBuilder() {
   private final boolean retryAbortsInternally;
   private final boolean useVirtualThreads;
   private final boolean useVirtualGrpcTransportThreads;
+  private final boolean enableOpenTelemetryMetrics;
+  private final OpenTelemetry openTelemetry;
   private final List<StatementExecutionInterceptor> statementExecutionInterceptors;
   private final SpannerOptionsConfigurator configurator;
 
@@ -792,6 +811,8 @@ private ConnectionOptions(Builder builder) {
     this.retryAbortsInternally = parseRetryAbortsInternally(this.uri);
     this.useVirtualThreads = parseUseVirtualThreads(this.uri);
     this.useVirtualGrpcTransportThreads = parseUseVirtualGrpcTransportThreads(this.uri);
+    this.enableOpenTelemetryMetrics = parseEnableOpenTelemetryMetrics(this.uri);
+    this.openTelemetry = builder.openTelemetry;
     this.statementExecutionInterceptors =
         Collections.unmodifiableList(builder.statementExecutionInterceptors);
     this.configurator = builder.configurator;
@@ -856,6 +877,19 @@ private static Integer parseIntegerProperty(String propertyName, String value) {
     return null;
   }
 
+  /**
+   * Returns an instance of OpenTelemetry. If OpenTelemetry object is not set then
+   * GlobalOpenTelemetry will be used as fallback.
+   */
+  @Nonnull
+  OpenTelemetry getOpenTelemetry() {
+    if (this.openTelemetry != null) {
+      return this.openTelemetry;
+    } else {
+      return GlobalOpenTelemetry.get();
+    }
+  }
+
   SpannerOptionsConfigurator getConfigurator() {
     return configurator;
   }
@@ -906,6 +940,12 @@ static boolean parseUseVirtualGrpcTransportThreads(String uri) {
     return value != null ? Boolean.parseBoolean(value) : DEFAULT_USE_VIRTUAL_GRPC_TRANSPORT_THREADS;
   }
 
+  @VisibleForTesting
+  static boolean parseEnableOpenTelemetryMetrics(String uri) {
+    String value = parseUriProperty(uri, ENABLE_OPENTELEMETRY_METRICS_PROPERTY_NAME);
+    return value != null ? Boolean.parseBoolean(value) : DEFAULT_ENABLE_OPENTELEMETRY_METRICS;
+  }
+
   @VisibleForTesting
   static @Nullable String parseCredentials(String uri) {
     String value = parseUriProperty(uri, CREDENTIALS_PROPERTY_NAME);
@@ -1336,6 +1376,11 @@ public boolean isUseVirtualGrpcTransportThreads() {
     return useVirtualGrpcTransportThreads;
   }
 
+  /** Whether connections should enable OpenTelemetry metrics. */
+  public boolean isEnabledOpenTelemetryMetrics() {
+    return enableOpenTelemetryMetrics;
+  }
+
   /** Any warnings that were generated while creating the {@link ConnectionOptions} instance. */
   @Nullable
   public String getWarnings() {

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

@@ -156,6 +156,7 @@ static class SpannerPoolKey {
     private final String databaseRole;
     private final boolean routeToLeader;
     private final boolean useVirtualGrpcTransportThreads;
+    private final boolean enableOpenTelemetryMetrics;
 
     @VisibleForTesting
     static SpannerPoolKey of(ConnectionOptions options) {
@@ -183,6 +184,7 @@ private SpannerPoolKey(ConnectionOptions options) throws IOException {
       this.userAgent = options.getUserAgent();
       this.routeToLeader = options.isRouteToLeader();
       this.useVirtualGrpcTransportThreads = options.isUseVirtualGrpcTransportThreads();
+      this.enableOpenTelemetryMetrics = options.isEnabledOpenTelemetryMetrics();
     }
 
     @Override
@@ -201,7 +203,8 @@ public boolean equals(Object o) {
           && Objects.equals(this.userAgent, other.userAgent)
           && Objects.equals(this.routeToLeader, other.routeToLeader)
           && Objects.equals(
-              this.useVirtualGrpcTransportThreads, other.useVirtualGrpcTransportThreads);
+              this.useVirtualGrpcTransportThreads, other.useVirtualGrpcTransportThreads)
+          && Objects.equals(this.enableOpenTelemetryMetrics, other.enableOpenTelemetryMetrics);
     }
 
     @Override
@@ -216,7 +219,8 @@ public int hashCode() {
           this.databaseRole,
           this.userAgent,
           this.routeToLeader,
-          this.useVirtualGrpcTransportThreads);
+          this.useVirtualGrpcTransportThreads,
+          this.enableOpenTelemetryMetrics);
     }
   }
 
@@ -337,6 +341,10 @@ private void initialize() {
 
   @VisibleForTesting
   Spanner createSpanner(SpannerPoolKey key, ConnectionOptions options) {
+    if (key.enableOpenTelemetryMetrics
+        && !ConnectionSpannerOptions.isEnabledOpenTelemetryMetrics()) {
+      ConnectionSpannerOptions.enableOpenTelemetryMetrics();
+    }
     ConnectionSpannerOptions.Builder builder = ConnectionSpannerOptions.newBuilder();
     builder
         .setUseVirtualThreads(key.useVirtualGrpcTransportThreads)
@@ -349,6 +357,9 @@ Spanner createSpanner(SpannerPoolKey key, ConnectionOptions options) {
         .setDatabaseRole(options.getDatabaseRole())
         .setCredentials(options.getCredentials());
     builder.setSessionPoolOption(key.sessionPoolOptions);
+    if (key.enableOpenTelemetryMetrics) {
+      builder.setOpenTelemetry(options.getOpenTelemetry());
+    }
     if (key.numChannels != null) {
       builder.setNumChannels(key.numChannels);
     }

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

@@ -1087,4 +1087,30 @@ public void testUseVirtualGrpcTransportThreads() {
             .build()
             .isUseVirtualThreads());
   }
+
+  @Test
+  public void testEnableOpenTelemetryMetrics() {
+    assertTrue(
+        ConnectionOptions.newBuilder()
+            .setUri(
+                "cloudspanner:/projects/test-project-123/instances/test-instance/databases/test-database?enableOpenTelemetryMetrics=true")
+            .setCredentials(NoCredentials.getInstance())
+            .build()
+            .isEnabledOpenTelemetryMetrics());
+    assertFalse(
+        ConnectionOptions.newBuilder()
+            .setUri(
+                "cloudspanner:/projects/test-project-123/instances/test-instance/databases/test-database?enableOpenTelemetryMetrics=false")
+            .setCredentials(NoCredentials.getInstance())
+            .build()
+            .isEnabledOpenTelemetryMetrics());
+    assertEquals(
+        ConnectionOptions.DEFAULT_ENABLE_OPENTELEMETRY_METRICS,
+        ConnectionOptions.newBuilder()
+            .setUri(
+                "cloudspanner:/projects/test-project-123/instances/test-instance/databases/test-database")
+            .setCredentials(NoCredentials.getInstance())
+            .build()
+            .isEnabledOpenTelemetryMetrics());
+  }
 }

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

@@ -69,6 +69,9 @@ public class SpannerPoolTest {
   private ConnectionOptions options7 = mock(ConnectionOptions.class);
   private ConnectionOptions options8 = mock(ConnectionOptions.class);
 
+  private ConnectionOptions optionsDisabledMetrics = mock(ConnectionOptions.class);
+  private ConnectionOptions optionsEnabledMetrics = mock(ConnectionOptions.class);
+
   private SpannerPool createSubjectAndMocks() {
     return createSubjectAndMocks(0L, Ticker.systemTicker());
   }
@@ -101,6 +104,12 @@ Spanner createSpanner(SpannerPoolKey key, ConnectionOptions options) {
     when(options8.getProjectId()).thenReturn("test-project-3");
     when(options8.isRouteToLeader()).thenReturn(false);
 
+    // ConnectionOptions disabling/enabling OpenTelemetry metrics.
+    when(optionsDisabledMetrics.getProjectId()).thenReturn("test-project-3");
+    when(optionsDisabledMetrics.isEnabledOpenTelemetryMetrics()).thenReturn(false);
+    when(optionsEnabledMetrics.getProjectId()).thenReturn("test-project-3");
+    when(optionsEnabledMetrics.isEnabledOpenTelemetryMetrics()).thenReturn(true);
+
     return pool;
   }
 
@@ -498,4 +507,29 @@ public void testSpannerPoolKeyEquality() {
     assertEquals(key3, key4);
     assertNotEquals(key4, key5);
   }
+
+  @Test
+  public void testGetSpannerForEnablingOpenTelemetryMetrics() {
+    SpannerPool pool = createSubjectAndMocks();
+    Spanner spanner1;
+    Spanner spanner2;
+
+    // assert equal
+    spanner1 = pool.getSpanner(optionsEnabledMetrics, connection1);
+    spanner2 = pool.getSpanner(optionsEnabledMetrics, connection2);
+    assertEquals(spanner1, spanner2);
+
+    spanner1 = pool.getSpanner(optionsDisabledMetrics, connection1);
+    spanner2 = pool.getSpanner(optionsDisabledMetrics, connection2);
+    assertEquals(spanner1, spanner2);
+
+    // assert not equal
+    spanner1 = pool.getSpanner(optionsDisabledMetrics, connection1);
+    spanner2 = pool.getSpanner(optionsEnabledMetrics, connection2);
+    assertNotEquals(spanner1, spanner2);
+
+    spanner1 = pool.getSpanner(optionsEnabledMetrics, connection1);
+    spanner2 = pool.getSpanner(optionsDisabledMetrics, connection2);
+    assertNotEquals(spanner1, spanner2);
+  }
 }