feat: Instrument HTTP with OpenTelemetry

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 setOpenTelemetrySdk(io.opentelemetry.sdk.OpenTelemetrySdk)</method>
+  </difference>
+
+  <difference>
+    <differenceType>7013</differenceType>
+    <className>com/google/cloud/storage/StorageOptions</className>
+    <method>io.opentelemetry.sdk.OpenTelemetrySdk getOpenTelemetrySdk()</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

@@ -78,6 +78,7 @@
 import io.grpc.MethodDescriptor;
 import io.grpc.Status;
 import io.grpc.protobuf.ProtoUtils;
+import io.opentelemetry.sdk.OpenTelemetrySdk;
 import java.io.Closeable;
 import java.io.IOException;
 import java.io.InputStream;
@@ -347,6 +348,11 @@ private Tuple<StorageSettings, Opts<UserProject>> resolveSettingsAndOpts() throw
     return Tuple.of(builder.build(), defaultOpts);
   }
 
+  @Override
+  public OpenTelemetrySdk getOpenTelemetrySdk() {
+    return null;
+  }
+
   /** @since 2.14.0 This new api is in preview and is subject to breaking changes. */
   @BetaApi
   @Override
@@ -628,6 +634,11 @@ public GrpcStorageOptions.Builder setBlobWriteSessionConfig(
       return this;
     }
 
+    @Override
+    public StorageOptions.Builder setOpenTelemetrySdk(@NonNull OpenTelemetrySdk openTelemetrySdk) {
+      return null;
+    }
+
     /** @since 2.14.0 This new api is in preview and is subject to breaking changes. */
     @BetaApi
     @Override

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.sdk.OpenTelemetrySdk;
 import java.io.IOException;
 import java.io.ObjectInputStream;
 import java.io.Serializable;
@@ -60,6 +61,8 @@ public class HttpStorageOptions extends StorageOptions {
   private transient RetryDependenciesAdapter retryDepsAdapter;
   private final BlobWriteSessionConfig blobWriteSessionConfig;
 
+  private OpenTelemetrySdk openTelemetrySdk;
+
   private HttpStorageOptions(Builder builder, StorageDefaults serviceDefaults) {
     super(builder, serviceDefaults);
     this.retryAlgorithmManager =
@@ -68,6 +71,7 @@ private HttpStorageOptions(Builder builder, StorageDefaults serviceDefaults) {
                 builder.storageRetryStrategy, defaults().getStorageRetryStrategy()));
     retryDepsAdapter = new RetryDependenciesAdapter();
     blobWriteSessionConfig = builder.blobWriteSessionConfig;
+    openTelemetrySdk = builder.openTelemetrySdk;
   }
 
   @Override
@@ -85,6 +89,11 @@ StorageRpc getStorageRpcV1() {
     return (StorageRpc) getRpc();
   }
 
+  @Override
+  public OpenTelemetrySdk getOpenTelemetrySdk() {
+    return openTelemetrySdk;
+  }
+
   @Override
   public HttpStorageOptions.Builder toBuilder() {
     return new HttpStorageOptions.Builder(this);
@@ -131,11 +140,16 @@ RetryingDependencies asRetryDependencies() {
     return retryDepsAdapter;
   }
 
+  public void setOpenTelemetrySdk(OpenTelemetrySdk openTelemetrySdk) {
+    this.openTelemetrySdk = openTelemetrySdk;
+  }
+
   public static class Builder extends StorageOptions.Builder {
 
     private StorageRetryStrategy storageRetryStrategy;
     private BlobWriteSessionConfig blobWriteSessionConfig =
         HttpStorageDefaults.INSTANCE.getDefaultStorageWriterConfig();
+    private OpenTelemetrySdk openTelemetrySdk;
 
     Builder() {}
 
@@ -144,6 +158,7 @@ public static class Builder extends StorageOptions.Builder {
       HttpStorageOptions hso = (HttpStorageOptions) options;
       this.storageRetryStrategy = hso.retryAlgorithmManager.retryStrategy;
       this.blobWriteSessionConfig = hso.blobWriteSessionConfig;
+      this.openTelemetrySdk = hso.getOpenTelemetrySdk();
     }
 
     @Override
@@ -269,6 +284,17 @@ public HttpStorageOptions build() {
       }
       return options;
     }
+
+    /**
+     * Enable OpenTelemetry Tracing and provide an instance for the client to use.
+     *
+     * @param openTelemetrySdk
+     */
+    public HttpStorageOptions.Builder setOpenTelemetrySdk(OpenTelemetrySdk openTelemetrySdk) {
+      requireNonNull(openTelemetrySdk, "openTelemetry must be non null");
+      this.openTelemetrySdk = openTelemetrySdk;
+      return this;
+    }
   }
 
   public static final class HttpStorageDefaults extends StorageDefaults {

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

@@ -29,6 +29,7 @@
 import com.google.cloud.storage.Storage.BlobWriteOption;
 import com.google.cloud.storage.TransportCompatibility.Transport;
 import com.google.cloud.storage.spi.StorageRpcFactory;
+import io.opentelemetry.sdk.OpenTelemetrySdk;
 import java.io.IOException;
 import java.io.InputStream;
 import java.util.Properties;
@@ -110,6 +111,9 @@ public abstract static class Builder
     public abstract StorageOptions.Builder setBlobWriteSessionConfig(
         @NonNull BlobWriteSessionConfig blobWriteSessionConfig);
 
+    public abstract StorageOptions.Builder setOpenTelemetrySdk(
+        @NonNull OpenTelemetrySdk openTelemetrySdk);
+
     @Override
     public abstract StorageOptions build();
   }
@@ -144,6 +148,8 @@ public static String version() {
     return VERSION;
   }
 
+  public abstract OpenTelemetrySdk getOpenTelemetrySdk();
+
   @SuppressWarnings("unchecked")
   @Override
   public abstract StorageOptions.Builder toBuilder();

google-cloud-storage/src/main/java/com/google/cloud/storage/otel/NoOpOpenTelemetryInstance.java

@@ -0,0 +1,96 @@
+/*
+ * 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.storage.otel;
+
+import com.google.api.core.ApiFuture;
+import io.opentelemetry.api.trace.StatusCode;
+import java.util.Map;
+import javax.annotation.Nonnull;
+
+class NoOpOpenTelemetryInstance implements OpenTelemetryTraceUtil {
+
+  @Override
+  public OpenTelemetryTraceUtil.Span startSpan(String spanName) {
+    return new Span();
+  }
+
+  @Override
+  public OpenTelemetryTraceUtil.Span startSpan(
+      String spanName, OpenTelemetryTraceUtil.Context parent) {
+    return new Span();
+  }
+
+  @Nonnull
+  @Override
+  public Span currentSpan() {
+    return new Span();
+  }
+
+  @Nonnull
+  @Override
+  public Context currentContext() {
+    return new Context();
+  }
+
+  static class Span implements OpenTelemetryTraceUtil.Span {
+    @Override
+    public void end() {}
+
+    @Override
+    public void end(Throwable error) {}
+
+    @Override
+    public <T> void endAtFuture(ApiFuture<T> futureValue) {}
+
+    @Override
+    public OpenTelemetryTraceUtil.Span recordException(Throwable error) {
+      return this;
+    }
+
+    @Override
+    public OpenTelemetryTraceUtil.Span setStatus(StatusCode status, String name) {
+      return this;
+    }
+
+    @Override
+    public OpenTelemetryTraceUtil.Span addEvent(String name) {
+      return this;
+    }
+
+    @Override
+    public OpenTelemetryTraceUtil.Span addEvent(String name, Map<String, Object> attributes) {
+      return this;
+    }
+
+    @Override
+    public Scope makeCurrent() {
+      return new Scope();
+    }
+  }
+
+  static class Context implements OpenTelemetryTraceUtil.Context {
+    @Override
+    public Scope makeCurrent() {
+      return new Scope();
+    }
+  }
+
+  static class Scope implements OpenTelemetryTraceUtil.Scope {
+    @Override
+    public void close() {}
+  }
+}