feat(storage): OpenTelemetry client metrics infrastructure and configuration

java-storage/google-cloud-storage/pom.xml

@@ -241,6 +241,11 @@
       <artifactId>opentelemetry-sdk-trace</artifactId>
       <scope>test</scope>
     </dependency>
+    <dependency>
+      <groupId>io.opentelemetry</groupId>
+      <artifactId>opentelemetry-sdk-testing</artifactId>
+      <scope>test</scope>
+    </dependency>
 
     <dependency>
       <groupId>io.grpc</groupId>

java-storage/google-cloud-storage/src/main/java/com/google/cloud/storage/GrpcStorageOptions.java

@@ -100,6 +100,7 @@
 import io.grpc.StatusRuntimeException;
 import io.grpc.protobuf.ProtoUtils;
 import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.sdk.metrics.SdkMeterProvider;
 import java.io.Closeable;
 import java.io.IOException;
 import java.io.InputStream;
@@ -122,6 +123,7 @@
 import java.util.concurrent.ScheduledExecutorService;
 import java.util.logging.Logger;
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
 
 /**
  * @since 2.14.0
@@ -148,6 +150,10 @@ public final class GrpcStorageOptions extends StorageOptions
   private final GrpcInterceptorProvider grpcInterceptorProvider;
   private final BlobWriteSessionConfig blobWriteSessionConfig;
   private transient OpenTelemetry openTelemetry;
+  private final boolean enableOtelMetrics;
+  private final boolean enableOtelDebugMetrics;
+  private final transient SdkMeterProvider meterProvider;
+  private final Duration metricInterval;
 
   private GrpcStorageOptions(Builder builder, GrpcStorageDefaults serviceDefaults) {
     super(builder, serviceDefaults);
@@ -165,6 +171,16 @@ private GrpcStorageOptions(Builder builder, GrpcStorageDefaults serviceDefaults)
     this.grpcInterceptorProvider = builder.grpcInterceptorProvider;
     this.blobWriteSessionConfig = builder.blobWriteSessionConfig;
     this.openTelemetry = builder.openTelemetry;
+    this.enableOtelMetrics =
+        builder.enableOtelMetrics != null
+            ? builder.enableOtelMetrics
+            : StorageMetricsConfig.isEnableOtelMetrics();
+    this.enableOtelDebugMetrics =
+        builder.enableOtelDebugMetrics != null
+            ? builder.enableOtelDebugMetrics
+            : StorageMetricsConfig.isEnableOtelDebugMetrics();
+    this.meterProvider = builder.meterProvider;
+    this.metricInterval = builder.metricInterval;
   }
 
   @Override
@@ -414,6 +430,42 @@ public OpenTelemetry getOpenTelemetry() {
     return openTelemetry;
   }
 
+  /**
+   * @since 2.50.0 This new api is in preview and is subject to breaking changes.
+   */
+  @BetaApi
+  @Override
+  public boolean isEnableOtelMetrics() {
+    return enableOtelMetrics;
+  }
+
+  /**
+   * @since 2.50.0 This new api is in preview and is subject to breaking changes.
+   */
+  @BetaApi
+  @Override
+  public boolean isEnableOtelDebugMetrics() {
+    return enableOtelDebugMetrics;
+  }
+
+  /**
+   * @since 2.50.0 This new api is in preview and is subject to breaking changes.
+   */
+  @BetaApi
+  @Override
+  public @Nullable SdkMeterProvider getMeterProvider() {
+    return meterProvider;
+  }
+
+  /**
+   * @since 2.50.0 This new api is in preview and is subject to breaking changes.
+   */
+  @BetaApi
+  @Override
+  public Duration getMetricInterval() {
+    return metricInterval;
+  }
+
   /**
    * @since 2.14.0
    */
@@ -432,6 +484,10 @@ public int hashCode() {
         grpcInterceptorProvider,
         blobWriteSessionConfig,
         openTelemetry,
+        enableOtelMetrics,
+        enableOtelDebugMetrics,
+        meterProvider,
+        metricInterval,
         baseHashCode());
   }
 
@@ -446,11 +502,15 @@ public boolean equals(Object o) {
     GrpcStorageOptions that = (GrpcStorageOptions) o;
     return attemptDirectPath == that.attemptDirectPath
         && enableGrpcClientMetrics == that.enableGrpcClientMetrics
+        && enableOtelMetrics == that.enableOtelMetrics
+        && enableOtelDebugMetrics == that.enableOtelDebugMetrics
         && Objects.equals(retryAlgorithmManager, that.retryAlgorithmManager)
         && Objects.equals(terminationAwaitDuration, that.terminationAwaitDuration)
         && Objects.equals(grpcInterceptorProvider, that.grpcInterceptorProvider)
         && Objects.equals(blobWriteSessionConfig, that.blobWriteSessionConfig)
         && Objects.equals(openTelemetry, that.openTelemetry)
+        && Objects.equals(meterProvider, that.meterProvider)
+        && Objects.equals(metricInterval, that.metricInterval)
         && this.baseEquals(that);
   }
 
@@ -501,6 +561,10 @@ public static final class Builder extends StorageOptions.Builder {
     private BlobWriteSessionConfig blobWriteSessionConfig =
         GrpcStorageDefaults.INSTANCE.getDefaultStorageWriterConfig();
     private OpenTelemetry openTelemetry = GrpcStorageDefaults.INSTANCE.getDefaultOpenTelemetry();
+    private Boolean enableOtelMetrics = null;
+    private Boolean enableOtelDebugMetrics = null;
+    private SdkMeterProvider meterProvider = null;
+    private Duration metricInterval = Duration.ofSeconds(60);
 
     private boolean grpcMetricsManuallyEnabled = false;
 
@@ -516,6 +580,10 @@ public static final class Builder extends StorageOptions.Builder {
       this.grpcInterceptorProvider = gso.grpcInterceptorProvider;
       this.blobWriteSessionConfig = gso.blobWriteSessionConfig;
       this.openTelemetry = gso.openTelemetry;
+      this.enableOtelMetrics = gso.isEnableOtelMetrics();
+      this.enableOtelDebugMetrics = gso.isEnableOtelDebugMetrics();
+      this.meterProvider = gso.getMeterProvider();
+      this.metricInterval = gso.getMetricInterval();
     }
 
     /**
@@ -750,6 +818,58 @@ public GrpcStorageOptions.Builder setOpenTelemetry(OpenTelemetry openTelemetry)
       return this;
     }
 
+    /**
+     * Enable or disable OpenTelemetry client metrics.
+     *
+     * @param enableOtelMetrics whether OpenTelemetry client metrics should be enabled
+     * @since 2.50.0 This new api is in preview and is subject to breaking changes.
+     */
+    @BetaApi
+    @Override
+    public GrpcStorageOptions.Builder setEnableOtelMetrics(boolean enableOtelMetrics) {
+      this.enableOtelMetrics = enableOtelMetrics;
+      return this;
+    }
+
+    /**
+     * Enable or disable OpenTelemetry debug client metrics.
+     *
+     * @param enableOtelDebugMetrics whether OpenTelemetry debug client metrics should be enabled
+     * @since 2.50.0 This new api is in preview and is subject to breaking changes.
+     */
+    @BetaApi
+    @Override
+    public GrpcStorageOptions.Builder setEnableOtelDebugMetrics(boolean enableOtelDebugMetrics) {
+      this.enableOtelDebugMetrics = enableOtelDebugMetrics;
+      return this;
+    }
+
+    /**
+     * Set a custom {@link SdkMeterProvider} for recording client metrics.
+     *
+     * @param meterProvider custom SdkMeterProvider to use
+     * @since 2.50.0 This new api is in preview and is subject to breaking changes.
+     */
+    @BetaApi
+    @Override
+    public GrpcStorageOptions.Builder setMeterProvider(SdkMeterProvider meterProvider) {
+      this.meterProvider = meterProvider;
+      return this;
+    }
+
+    /**
+     * Set the metric export interval for periodic metric reading.
+     *
+     * @param metricInterval interval duration
+     * @since 2.50.0 This new api is in preview and is subject to breaking changes.
+     */
+    @BetaApi
+    @Override
+    public GrpcStorageOptions.Builder setMetricInterval(Duration metricInterval) {
+      this.metricInterval = requireNonNull(metricInterval, "metricInterval must be non null");
+      return this;
+    }
+
     /**
      * @since 2.14.0
      */