feat: introductory beta level support for OpenTelemetry tracing on c.g.c.storage.Storage methods (#2837)

Author: sydney-munro

google-cloud-storage/clirr-ignored-differences.xml

@@ -96,4 +96,17 @@
     <method>boolean equals(java.lang.Object)</method>
   </difference>
 
+  <difference>
+    <differenceType>7013</differenceType>
+    <className>com/google/cloud/storage/StorageOptions$Builder</className>
+    <method>com.google.cloud.storage.StorageOptions$Builder setOpenTelemetry(io.opentelemetry.api.OpenTelemetry)</method>
+  </difference>
+
+  <difference>
+    <differenceType>7013</differenceType>
+    <className>com/google/cloud/storage/StorageOptions</className>
+    <method>io.opentelemetry.api.OpenTelemetry getOpenTelemetry()</method>
+  </difference>
+
+
 </differences>

google-cloud-storage/pom.xml

@@ -83,6 +83,10 @@
       <groupId>io.opencensus</groupId>
       <artifactId>opencensus-api</artifactId>
     </dependency>
+    <dependency>
+      <groupId>io.opentelemetry</groupId>
+      <artifactId>opentelemetry-context</artifactId>
+    </dependency>
     <dependency>
       <groupId>com.google.api.grpc</groupId>
       <artifactId>proto-google-iam-v1</artifactId>
@@ -205,6 +209,11 @@
       <artifactId>grpc-googleapis</artifactId>
       <scope>runtime</scope>
     </dependency>
+    <dependency>
+      <groupId>io.opentelemetry</groupId>
+      <artifactId>opentelemetry-sdk-trace</artifactId>
+      <scope>test</scope>
+    </dependency>
 
     <!--
     We're not using this directly, however there appears to be some resolution

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

@@ -81,9 +81,11 @@
 import io.grpc.MethodDescriptor;
 import io.grpc.Status;
 import io.grpc.protobuf.ProtoUtils;
+import io.opentelemetry.api.OpenTelemetry;
 import java.io.Closeable;
 import java.io.IOException;
 import java.io.InputStream;
+import java.io.ObjectInputStream;
 import java.io.Serializable;
 import java.net.URI;
 import java.nio.ByteBuffer;
@@ -119,6 +121,7 @@ public final class GrpcStorageOptions extends StorageOptions
   private final boolean grpcClientMetricsManuallyEnabled;
   private final GrpcInterceptorProvider grpcInterceptorProvider;
   private final BlobWriteSessionConfig blobWriteSessionConfig;
+  private transient OpenTelemetry openTelemetry;
 
   private GrpcStorageOptions(Builder builder, GrpcStorageDefaults serviceDefaults) {
     super(builder, serviceDefaults);
@@ -135,6 +138,7 @@ private GrpcStorageOptions(Builder builder, GrpcStorageDefaults serviceDefaults)
     this.grpcClientMetricsManuallyEnabled = builder.grpcMetricsManuallyEnabled;
     this.grpcInterceptorProvider = builder.grpcInterceptorProvider;
     this.blobWriteSessionConfig = builder.blobWriteSessionConfig;
+    this.openTelemetry = builder.openTelemetry;
   }
 
   @Override
@@ -157,6 +161,11 @@ StorageSettings getStorageSettings() throws IOException {
     return resolveSettingsAndOpts().x();
   }
 
+  private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {
+    in.defaultReadObject();
+    this.openTelemetry = HttpStorageOptions.getDefaultInstance().getOpenTelemetry();
+  }
+
   /**
    * We have to perform several introspections and detections to cross-wire/support several features
    * that are either gapic primitives, ServiceOption primitives or GCS semantic requirements.
@@ -349,6 +358,13 @@ private Tuple<StorageSettings, Opts<UserProject>> resolveSettingsAndOpts() throw
     return Tuple.of(builder.build(), defaultOpts);
   }
 
+  /** @since 2.47.0 This new api is in preview and is subject to breaking changes. */
+  @BetaApi
+  @Override
+  public OpenTelemetry getOpenTelemetry() {
+    return openTelemetry;
+  }
+
   /** @since 2.14.0 */
   @Override
   public GrpcStorageOptions.Builder toBuilder() {
@@ -364,6 +380,7 @@ public int hashCode() {
         enableGrpcClientMetrics,
         grpcInterceptorProvider,
         blobWriteSessionConfig,
+        openTelemetry,
         baseHashCode());
   }
 
@@ -382,6 +399,7 @@ public boolean equals(Object o) {
         && Objects.equals(terminationAwaitDuration, that.terminationAwaitDuration)
         && Objects.equals(grpcInterceptorProvider, that.grpcInterceptorProvider)
         && Objects.equals(blobWriteSessionConfig, that.blobWriteSessionConfig)
+        && Objects.equals(openTelemetry, that.openTelemetry)
         && this.baseEquals(that);
   }
 
@@ -423,6 +441,7 @@ public static final class Builder extends StorageOptions.Builder {
         GrpcStorageDefaults.INSTANCE.grpcInterceptorProvider();
     private BlobWriteSessionConfig blobWriteSessionConfig =
         GrpcStorageDefaults.INSTANCE.getDefaultStorageWriterConfig();
+    private OpenTelemetry openTelemetry = GrpcStorageDefaults.INSTANCE.getDefaultOpenTelemetry();
 
     private boolean grpcMetricsManuallyEnabled = false;
 
@@ -437,6 +456,7 @@ public static final class Builder extends StorageOptions.Builder {
       this.enableGrpcClientMetrics = gso.enableGrpcClientMetrics;
       this.grpcInterceptorProvider = gso.grpcInterceptorProvider;
       this.blobWriteSessionConfig = gso.blobWriteSessionConfig;
+      this.openTelemetry = gso.openTelemetry;
     }
 
     /**
@@ -619,6 +639,19 @@ public GrpcStorageOptions.Builder setBlobWriteSessionConfig(
       return this;
     }
 
+    /**
+     * Enable OpenTelemetry Tracing and provide an instance for the client to use.
+     *
+     * @param openTelemetry User defined instance of OpenTelemetry to be used by the library
+     * @since 2.47.0 This new api is in preview and is subject to breaking changes.
+     */
+    @BetaApi
+    public GrpcStorageOptions.Builder setOpenTelemetry(OpenTelemetry openTelemetry) {
+      requireNonNull(openTelemetry, "openTelemetry must be non null");
+      this.openTelemetry = openTelemetry;
+      return this;
+    }
+
     /** @since 2.14.0 */
     @Override
     public GrpcStorageOptions build() {
@@ -695,6 +728,12 @@ public GrpcInterceptorProvider grpcInterceptorProvider() {
     public BlobWriteSessionConfig getDefaultStorageWriterConfig() {
       return BlobWriteSessionConfigs.getDefault();
     }
+
+    /** @since 2.47.0 This new api is in preview and is subject to breaking changes. */
+    @BetaApi
+    public OpenTelemetry getDefaultOpenTelemetry() {
+      return OpenTelemetry.noop();
+    }
   }
 
   /**
@@ -751,22 +790,27 @@ public Storage create(StorageOptions options) {
                 new InternalZeroCopyGrpcStorageStub(
                     stubSettings, clientContext, grpcStorageCallableFactory);
             StorageClient client = new InternalStorageClient(stub);
-            return new GrpcStorageImpl(
-                grpcStorageOptions,
-                client,
-                stub.getObjectMediaResponseMarshaller,
-                grpcStorageOptions.blobWriteSessionConfig.createFactory(Clock.systemUTC()),
-                defaultOpts);
+            GrpcStorageImpl grpcStorage =
+                new GrpcStorageImpl(
+                    grpcStorageOptions,
+                    client,
+                    stub.getObjectMediaResponseMarshaller,
+                    grpcStorageOptions.blobWriteSessionConfig.createFactory(Clock.systemUTC()),
+                    defaultOpts);
+            return OtelStorageDecorator.decorate(
+                grpcStorage, options.getOpenTelemetry(), Transport.GRPC);
           } else {
             StorageClient client = StorageClient.create(storageSettings);
-            return new GrpcStorageImpl(
-                grpcStorageOptions,
-                client,
-                ResponseContentLifecycleManager.noop(),
-                grpcStorageOptions.blobWriteSessionConfig.createFactory(Clock.systemUTC()),
-                defaultOpts);
+            GrpcStorageImpl grpcStorage =
+                new GrpcStorageImpl(
+                    grpcStorageOptions,
+                    client,
+                    ResponseContentLifecycleManager.noop(),
+                    grpcStorageOptions.blobWriteSessionConfig.createFactory(Clock.systemUTC()),
+                    defaultOpts);
+            return OtelStorageDecorator.decorate(
+                grpcStorage, options.getOpenTelemetry(), Transport.GRPC);
           }
-
         } catch (IOException e) {
           throw new IllegalStateException(
               "Unable to instantiate gRPC com.google.cloud.storage.Storage client.", e);

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

@@ -38,6 +38,7 @@
 import com.google.cloud.storage.spi.v1.StorageRpc;
 import com.google.common.base.MoreObjects;
 import com.google.common.collect.ImmutableSet;
+import io.opentelemetry.api.OpenTelemetry;
 import java.io.IOException;
 import java.io.ObjectInputStream;
 import java.io.Serializable;
@@ -59,6 +60,8 @@ public class HttpStorageOptions extends StorageOptions {
   private transient RetryDependenciesAdapter retryDepsAdapter;
   private final BlobWriteSessionConfig blobWriteSessionConfig;
 
+  private transient OpenTelemetry openTelemetry;
+
   private HttpStorageOptions(Builder builder, StorageDefaults serviceDefaults) {
     super(builder, serviceDefaults);
     this.retryAlgorithmManager =
@@ -67,6 +70,7 @@ private HttpStorageOptions(Builder builder, StorageDefaults serviceDefaults) {
                 builder.storageRetryStrategy, defaults().getStorageRetryStrategy()));
     retryDepsAdapter = new RetryDependenciesAdapter();
     blobWriteSessionConfig = builder.blobWriteSessionConfig;
+    openTelemetry = builder.openTelemetry;
   }
 
   @Override
@@ -84,14 +88,22 @@ StorageRpc getStorageRpcV1() {
     return (StorageRpc) getRpc();
   }
 
+  /** @since 2.47.0 This new api is in preview and is subject to breaking changes. */
+  @BetaApi
+  @Override
+  public OpenTelemetry getOpenTelemetry() {
+    return openTelemetry;
+  }
+
   @Override
   public HttpStorageOptions.Builder toBuilder() {
     return new HttpStorageOptions.Builder(this);
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(retryAlgorithmManager, blobWriteSessionConfig, baseHashCode());
+    return Objects.hash(
+        retryAlgorithmManager, blobWriteSessionConfig, openTelemetry, baseHashCode());
   }
 
   @Override
@@ -105,12 +117,14 @@ public boolean equals(Object o) {
     HttpStorageOptions that = (HttpStorageOptions) o;
     return Objects.equals(retryAlgorithmManager, that.retryAlgorithmManager)
         && Objects.equals(blobWriteSessionConfig, that.blobWriteSessionConfig)
+        && Objects.equals(openTelemetry, that.openTelemetry)
         && this.baseEquals(that);
   }
 
   private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {
     in.defaultReadObject();
     this.retryDepsAdapter = new RetryDependenciesAdapter();
+    this.openTelemetry = HttpStorageOptions.getDefaultInstance().getOpenTelemetry();
   }
 
   public static HttpStorageOptions.Builder newBuilder() {
@@ -135,6 +149,7 @@ public static class Builder extends StorageOptions.Builder {
     private StorageRetryStrategy storageRetryStrategy;
     private BlobWriteSessionConfig blobWriteSessionConfig =
         HttpStorageDefaults.INSTANCE.getDefaultStorageWriterConfig();
+    private OpenTelemetry openTelemetry = HttpStorageDefaults.INSTANCE.getDefaultOpenTelemetry();
 
     Builder() {}
 
@@ -143,6 +158,7 @@ public static class Builder extends StorageOptions.Builder {
       HttpStorageOptions hso = (HttpStorageOptions) options;
       this.storageRetryStrategy = hso.retryAlgorithmManager.retryStrategy;
       this.blobWriteSessionConfig = hso.blobWriteSessionConfig;
+      this.openTelemetry = hso.getOpenTelemetry();
     }
 
     @Override
@@ -268,6 +284,19 @@ public HttpStorageOptions build() {
       }
       return options;
     }
+
+    /**
+     * Enable OpenTelemetry Tracing and provide an instance for the client to use.
+     *
+     * @param openTelemetry User defined instance of OpenTelemetry to be used by the library
+     * @since 2.47.0 This new api is in preview and is subject to breaking changes.
+     */
+    @BetaApi
+    public HttpStorageOptions.Builder setOpenTelemetry(OpenTelemetry openTelemetry) {
+      requireNonNull(openTelemetry, "openTelemetry must be non null");
+      this.openTelemetry = openTelemetry;
+      return this;
+    }
   }
 
   public static final class HttpStorageDefaults extends StorageDefaults {
@@ -301,6 +330,12 @@ public StorageRetryStrategy getStorageRetryStrategy() {
     public BlobWriteSessionConfig getDefaultStorageWriterConfig() {
       return BlobWriteSessionConfigs.getDefault();
     }
+
+    /** @since 2.47.0 This new api is in preview and is subject to breaking changes. */
+    @BetaApi
+    public OpenTelemetry getDefaultOpenTelemetry() {
+      return OpenTelemetry.noop();
+    }
   }
 
   /**
@@ -341,8 +376,12 @@ public Storage create(StorageOptions options) {
         HttpStorageOptions httpStorageOptions = (HttpStorageOptions) options;
         Clock clock = Clock.systemUTC();
         try {
-          return new StorageImpl(
-              httpStorageOptions, httpStorageOptions.blobWriteSessionConfig.createFactory(clock));
+          StorageImpl storage =
+              new StorageImpl(
+                  httpStorageOptions,
+                  httpStorageOptions.blobWriteSessionConfig.createFactory(clock));
+          return OtelStorageDecorator.decorate(
+              storage, httpStorageOptions.getOpenTelemetry(), Transport.HTTP);
         } catch (IOException e) {
           throw new IllegalStateException(
               "Unable to instantiate HTTP com.google.cloud.storage.Storage client.", e);