feat: Add com.google.cloud.firestore.telemetry package.

google-cloud-firestore/pom.xml

@@ -16,6 +16,7 @@
   </parent>
   <properties>
     <site.installationModule>google-cloud-firestore</site.installationModule>
+    <opentelemetry.version>1.29.0</opentelemetry.version>
   </properties>
   <dependencies>
     <dependency>
@@ -112,7 +113,23 @@
       <groupId>com.google.protobuf</groupId>
       <artifactId>protobuf-java-util</artifactId>
     </dependency>
-
+    <!-- OpenTelemetry -->
+    <dependency>
+      <groupId>io.opentelemetry</groupId>
+      <artifactId>opentelemetry-api</artifactId>
+      <version>${opentelemetry.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>io.opentelemetry</groupId>
+      <artifactId>opentelemetry-context</artifactId>
+      <version>${opentelemetry.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>io.opentelemetry.instrumentation</groupId>
+      <artifactId>opentelemetry-grpc-1.6</artifactId>
+      <version>${opentelemetry.version}-alpha</version>
+    </dependency>
+    <!-- END OpenTelemetry -->
 
     <!-- Test dependencies -->
     <dependency>
@@ -173,6 +190,14 @@
       <version>3.14.0</version>
       <scope>test</scope>
     </dependency>
+    <!-- OpenTelemetry -->
+    <dependency>
+      <groupId>io.opentelemetry</groupId>
+      <artifactId>opentelemetry-sdk</artifactId>
+      <version>${opentelemetry.version}</version>
+      <scope>test</scope>
+    </dependency>
+    <!-- END OpenTelemetry -->
   </dependencies>
 
   <reporting>

google-cloud-firestore/src/main/java/com/google/cloud/firestore/FirestoreOpenTelemetryOptions.java

@@ -0,0 +1,97 @@
+/*
+ * 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.firestore;
+
+import io.opentelemetry.api.OpenTelemetry;
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
+public class FirestoreOpenTelemetryOptions {
+  private final boolean enabled;
+
+  @Nullable private final OpenTelemetry openTelemetry;
+
+  FirestoreOpenTelemetryOptions(Builder builder) {
+    this.enabled = builder.enabled;
+    this.openTelemetry = builder.openTelemetry;
+  }
+
+  public boolean getEnabled() {
+    return enabled;
+  }
+
+  public OpenTelemetry getOpenTelemetry() {
+    return openTelemetry;
+  }
+
+  @Nonnull
+  public FirestoreOpenTelemetryOptions.Builder toBuilder() {
+    return new FirestoreOpenTelemetryOptions.Builder(this);
+  }
+
+  @Nonnull
+  public static FirestoreOpenTelemetryOptions.Builder newBuilder() {
+    return new FirestoreOpenTelemetryOptions.Builder();
+  }
+
+  public static class Builder {
+
+    private boolean enabled;
+
+    @Nullable private OpenTelemetry openTelemetry;
+
+    private Builder() {
+      enabled = false;
+      openTelemetry = null;
+    }
+
+    private Builder(FirestoreOpenTelemetryOptions options) {
+      this.enabled = options.enabled;
+      this.openTelemetry = options.openTelemetry;
+    }
+
+    @Nonnull
+    public FirestoreOpenTelemetryOptions build() {
+      return new FirestoreOpenTelemetryOptions(this);
+    }
+
+    /**
+     * Sets whether tracing should be enabled.
+     *
+     * @param enable Whether tracing should be enabled.
+     */
+    @Nonnull
+    public FirestoreOpenTelemetryOptions.Builder setTracingEnabled(boolean enable) {
+      this.enabled = enable;
+      return this;
+    }
+
+    /**
+     * Sets the {@link OpenTelemetry} to use with this Firestore instance. If telemetry collection
+     * is enabled, but an `OpenTelemetry` is not provided, the Firestore SDK will attempt to use the
+     * `GlobalOpenTelemetry`.
+     *
+     * @param openTelemetry The OpenTelemetry that should be used by this Firestore instance.
+     */
+    @Nonnull
+    public FirestoreOpenTelemetryOptions.Builder setOpenTelemetry(
+        @Nonnull OpenTelemetry openTelemetry) {
+      this.openTelemetry = openTelemetry;
+      return this;
+    }
+  }
+}

google-cloud-firestore/src/main/java/com/google/cloud/firestore/FirestoreOptions.java

@@ -16,6 +16,8 @@
 
 package com.google.cloud.firestore;
 
+import com.google.api.core.ApiFunction;
+import com.google.api.core.BetaApi;
 import com.google.api.core.InternalApi;
 import com.google.api.gax.core.CredentialsProvider;
 import com.google.api.gax.core.FixedCredentialsProvider;
@@ -60,6 +62,8 @@ public final class FirestoreOptions extends ServiceOptions<Firestore, FirestoreO
   private final TransportChannelProvider channelProvider;
   private final CredentialsProvider credentialsProvider;
   private final String emulatorHost;
+  @Nonnull private final FirestoreOpenTelemetryOptions openTelemetryOptions;
+  @Nonnull private final com.google.cloud.firestore.telemetry.TraceUtil traceUtil;
 
   public static class DefaultFirestoreFactory implements FirestoreFactory {
 
@@ -118,12 +122,24 @@ public String getEmulatorHost() {
     return emulatorHost;
   }
 
+  @Nonnull
+  com.google.cloud.firestore.telemetry.TraceUtil getTraceUtil() {
+    return traceUtil;
+  }
+
+  @BetaApi
+  @Nonnull
+  public FirestoreOpenTelemetryOptions getOpenTelemetryOptions() {
+    return openTelemetryOptions;
+  }
+
   public static class Builder extends ServiceOptions.Builder<Firestore, FirestoreOptions, Builder> {
 
     @Nullable private String databaseId = null;
     @Nullable private TransportChannelProvider channelProvider = null;
     @Nullable private CredentialsProvider credentialsProvider = null;
     @Nullable private String emulatorHost = null;
+    @Nullable private FirestoreOpenTelemetryOptions openTelemetryOptions = null;
 
     private Builder() {}
 
@@ -133,6 +149,7 @@ private Builder(FirestoreOptions options) {
       this.channelProvider = options.channelProvider;
       this.credentialsProvider = options.credentialsProvider;
       this.emulatorHost = options.emulatorHost;
+      this.openTelemetryOptions = options.openTelemetryOptions;
     }
 
     /**
@@ -201,6 +218,19 @@ public Builder setDatabaseId(@Nonnull String databaseId) {
       return this;
     }
 
+    /**
+     * Sets the {@link FirestoreOpenTelemetryOptions} to be used for this Firestore instance.
+     *
+     * @param openTelemetryOptions The `FirestoreOpenTelemetryOptions` to use.
+     */
+    @BetaApi
+    @Nonnull
+    public Builder setOpenTelemetryOptions(
+        @Nonnull FirestoreOpenTelemetryOptions openTelemetryOptions) {
+      this.openTelemetryOptions = openTelemetryOptions;
+      return this;
+    }
+
     @Override
     @Nonnull
     public FirestoreOptions build() {
@@ -212,6 +242,10 @@ public FirestoreOptions build() {
         }
       }
 
+      if (this.openTelemetryOptions == null) {
+        this.setOpenTelemetryOptions(FirestoreOpenTelemetryOptions.newBuilder().build());
+      }
+
       // Override credentials and channel provider if we are using the emulator.
       if (emulatorHost == null) {
         emulatorHost = System.getenv(FIRESTORE_EMULATOR_SYSTEM_VARIABLE);
@@ -278,16 +312,37 @@ public void refresh() {}
   protected FirestoreOptions(Builder builder) {
     super(FirestoreFactory.class, FirestoreRpcFactory.class, builder, new FirestoreDefaults());
 
+    if (builder.openTelemetryOptions == null) {
+      this.openTelemetryOptions = FirestoreOpenTelemetryOptions.newBuilder().build();
+    } else {
+      this.openTelemetryOptions = builder.openTelemetryOptions;
+    }
+
+    this.traceUtil = com.google.cloud.firestore.telemetry.TraceUtil.getInstance(this);
+
     this.databaseId =
         builder.databaseId != null
             ? builder.databaseId
             : FirestoreDefaults.INSTANCE.getDatabaseId();
 
-    this.channelProvider =
-        builder.channelProvider != null
-            ? builder.channelProvider
-            : GrpcTransportOptions.setUpChannelProvider(
+    if (builder.channelProvider == null) {
+      ApiFunction<ManagedChannelBuilder, ManagedChannelBuilder> channelConfigurator =
+          this.traceUtil.getChannelConfigurator();
+      if (channelConfigurator == null) {
+        this.channelProvider =
+            GrpcTransportOptions.setUpChannelProvider(
                 FirestoreSettings.defaultGrpcTransportProviderBuilder(), this);
+      } else {
+        // Intercept the grpc channel calls to add telemetry info.
+        this.channelProvider =
+            GrpcTransportOptions.setUpChannelProvider(
+                FirestoreSettings.defaultGrpcTransportProviderBuilder()
+                    .setChannelConfigurator(channelConfigurator),
+                this);
+      }
+    } else {
+      this.channelProvider = builder.channelProvider;
+    }
 
     this.credentialsProvider =
         builder.credentialsProvider != null

google-cloud-firestore/src/main/java/com/google/cloud/firestore/telemetry/DisabledTraceUtil.java

@@ -0,0 +1,103 @@
+/*
+ * 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.firestore.telemetry;
+
+import com.google.api.core.ApiFunction;
+import com.google.api.core.ApiFuture;
+import io.grpc.ManagedChannelBuilder;
+import java.util.Map;
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
+public class DisabledTraceUtil implements TraceUtil {
+
+  static class Span implements TraceUtil.Span {
+    @Override
+    public void end() {}
+
+    @Override
+    public void end(Throwable error) {}
+
+    @Override
+    public <T> void endAtFuture(ApiFuture<T> futureValue) {}
+
+    @Override
+    public TraceUtil.Span addEvent(String name) {
+      return this;
+    }
+
+    @Override
+    public TraceUtil.Span addEvent(String name, Map<String, Object> attributes) {
+      return this;
+    }
+
+    @Override
+    public TraceUtil.Span setAttribute(String key, int value) {
+      return this;
+    }
+
+    @Override
+    public TraceUtil.Span setAttribute(String key, String value) {
+      return this;
+    }
+
+    @Override
+    public Scope makeCurrent() {
+      return new Scope();
+    }
+  }
+
+  static class Context implements TraceUtil.Context {
+    @Override
+    public Scope makeCurrent() {
+      return new Scope();
+    }
+  }
+
+  static class Scope implements TraceUtil.Scope {
+    @Override
+    public void close() {}
+  }
+
+  @Nullable
+  @Override
+  public ApiFunction<ManagedChannelBuilder, ManagedChannelBuilder> getChannelConfigurator() {
+    return null;
+  }
+
+  @Override
+  public Span startSpan(String spanName) {
+    return new Span();
+  }
+
+  @Override
+  public TraceUtil.Span startSpan(String spanName, TraceUtil.Context parent) {
+    return new Span();
+  }
+
+  @Nonnull
+  @Override
+  public TraceUtil.Span currentSpan() {
+    return new Span();
+  }
+
+  @Nonnull
+  @Override
+  public TraceUtil.Context currentContext() {
+    return new DisabledTraceUtil.Context();
+  }
+}