add documentations/comments

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

@@ -314,4 +314,11 @@
     <method>com.google.cloud.firestore.Query getQuery()</method>
   </difference>
 
+    <!-- Relocate constants in TraceUtil -->
+  <difference>
+    <differenceType>6011</differenceType>
+    <className>com/google/cloud/firestore/telemetry/TraceUtil</className>
+    <field>SPAN_NAME_*</field>
+  </difference>
+
 </differences>

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

@@ -123,6 +123,10 @@ private ApiTracerFactory createApiTracerFactory() {
     }
     // Add Metrics Tracer factory if built in metrics are enabled.
     metricsUtil.addMetricsTracerFactory(apiTracerFactories);
+
+    if (apiTracerFactories.isEmpty()) {
+      return null;
+    }
     return new CompositeApiTracerFactory(apiTracerFactories);
   }
 

google-cloud-firestore/src/main/java/com/google/cloud/firestore/spi/v1/GrpcFirestoreRpc.java

@@ -28,6 +28,7 @@
 import com.google.api.gax.rpc.ServerStreamingCallable;
 import com.google.api.gax.rpc.TransportChannel;
 import com.google.api.gax.rpc.UnaryCallable;
+import com.google.api.gax.tracing.ApiTracerFactory;
 import com.google.cloud.NoCredentials;
 import com.google.cloud.ServiceOptions;
 import com.google.cloud.firestore.FirestoreOptions;
@@ -157,8 +158,9 @@ public GrpcFirestoreRpc(final FirestoreOptions options) throws IOException {
         firestoreBuilder.batchGetDocumentsSettings().setRetrySettings(retrySettings);
       }
 
-      if (options.getApiTracerFactory() != null) {
-        firestoreBuilder.setTracerFactory(options.getApiTracerFactory());
+      ApiTracerFactory apiTracerFactory = options.getApiTracerFactory();
+      if (apiTracerFactory != null) {
+        firestoreBuilder.setTracerFactory(apiTracerFactory);
       }
 
       firestoreStub = GrpcFirestoreStub.create(firestoreBuilder.build());

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

@@ -32,40 +32,65 @@
 import io.opentelemetry.api.common.AttributesBuilder;
 import io.opentelemetry.api.metrics.DoubleHistogram;
 import io.opentelemetry.api.metrics.Meter;
+import io.opentelemetry.api.metrics.MeterProvider;
 import java.util.HashMap;
 import java.util.Map;
 
-public class BuiltinMetricsProvider {
+/**
+ * A provider for built-in metrics. This class is responsible for storing OpenTelemetry metrics
+ * configuration and recording built-in metrics for the Firestore SDK.
+ */
+class BuiltinMetricsProvider {
   private OpenTelemetry openTelemetry;
-  private ApiTracerFactory apiTracerFactory;
-
   private Meter meter;
   private DoubleHistogram endToEndRequestLatency;
   private DoubleHistogram firstResponseLatency;
 
+  private ApiTracerFactory apiTracerFactory;
+  private final Map<String, String> staticAttributes;
+
   private static final String MILLISECOND_UNIT = "ms";
   private static final String FIRESTORE_LIBRARY_NAME = "java_firestore";
 
   public BuiltinMetricsProvider(OpenTelemetry openTelemetry) {
     this.openTelemetry = openTelemetry;
+    this.staticAttributes = createStaticAttributes();
 
-    if (openTelemetry != null) {
-      configureGaxLayerMetrics();
-      configureFirestoreLayerMetrics();
+    if (openTelemetry != null && openTelemetry.getMeterProvider() != MeterProvider.noop()) {
+      configureRPCLayerMetrics();
+      configureSDKLayerMetrics();
     }
   }
 
   public ApiTracerFactory getApiTracerFactory() {
     return this.apiTracerFactory;
   }
 
-  void configureGaxLayerMetrics() {
+  public void endToEndRequestLatencyRecorder(double latency, Map<String, String> attributes) {
+    recordLatency(endToEndRequestLatency, latency, attributes);
+  }
+
+  public void firstResponseLatencyRecorder(double latency, Map<String, String> attributes) {
+    recordLatency(firstResponseLatency, latency, attributes);
+  }
+
+  private void recordLatency(
+      DoubleHistogram latencyHistogram, double latency, Map<String, String> attributes) {
+    if (latencyHistogram != null) {
+      attributes.putAll(staticAttributes);
+      latencyHistogram.record(latency, toOtelAttributes(attributes));
+    }
+  }
+
+  /** Creates an ApiTracerFactory to be passed into GAX library and collect RPC layer metrics. */
+  private void configureRPCLayerMetrics() {
     OpenTelemetryMetricsRecorder recorder =
         new OpenTelemetryMetricsRecorder(openTelemetry, METRIC_PREFIX);
-    this.apiTracerFactory = new MetricsTracerFactory(recorder, createStaticAttributes());
+    this.apiTracerFactory = new MetricsTracerFactory(recorder, staticAttributes);
   }
 
-  void configureFirestoreLayerMetrics() {
+  /** Registers metrics to be collected at the Firestore SDK layer */
+  private void configureSDKLayerMetrics() {
     this.meter = openTelemetry.getMeter(FIRESTORE_METER_NAME);
 
     this.endToEndRequestLatency =
@@ -84,27 +109,13 @@ void configureFirestoreLayerMetrics() {
     // TODO(metrics): add transaction latency and retry count metrics
   }
 
-  public void endToEndRequestLatencyRecorder(double latency, Map<String, String> attributes) {
-    if (endToEndRequestLatency != null) {
-      attributes.putAll(createStaticAttributes());
-      endToEndRequestLatency.record(latency, toOtelAttributes(attributes));
-    }
-  }
-
-  public void firstResponseLatencyRecorder(double latency, Map<String, String> attributes) {
-    if (firstResponseLatency != null) {
-      attributes.putAll(createStaticAttributes());
-      firstResponseLatency.record(latency, toOtelAttributes(attributes));
-    }
-  }
-
   private Map<String, String> createStaticAttributes() {
     Map<String, String> staticAttributes = new HashMap<>();
-    staticAttributes.put(METRIC_KEY_CLIENT_UID.toString(), TelemetryHelper.getClientUid());
-    staticAttributes.put(METRIC_KEY_LIBRARY_NAME.toString(), FIRESTORE_LIBRARY_NAME);
+    staticAttributes.put(METRIC_KEY_CLIENT_UID.getKey(), ClientIdentifier.getClientUid());
+    staticAttributes.put(METRIC_KEY_LIBRARY_NAME.getKey(), FIRESTORE_LIBRARY_NAME);
     String pkgVersion = this.getClass().getPackage().getImplementationVersion();
     if (pkgVersion != null) {
-      staticAttributes.put(METRIC_KEY_LIBRARY_VERSION.toString(), pkgVersion);
+      staticAttributes.put(METRIC_KEY_LIBRARY_VERSION.getKey(), pkgVersion);
     }
     return staticAttributes;
   }

google-cloud-firestore/src/main/java/com/google/cloud/firestore/telemetry/TelemetryHelper.java → google-cloud-firestore/src/main/java/com/google/cloud/firestore/telemetry/ClientIdentifier.java

@@ -1,55 +1,46 @@
-package com.google.cloud.firestore.telemetry;
+/*
+ * 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.
+ */
 
-import static com.google.cloud.firestore.telemetry.TelemetryConstants.*;
+package com.google.cloud.firestore.telemetry;
 
-import com.google.common.collect.ImmutableMap;
-import com.google.common.collect.ImmutableSet;
-import io.opentelemetry.api.common.AttributeKey;
-import io.opentelemetry.sdk.metrics.InstrumentSelector;
-import io.opentelemetry.sdk.metrics.View;
 import java.lang.management.ManagementFactory;
 import java.lang.reflect.Method;
 import java.net.InetAddress;
 import java.net.UnknownHostException;
-import java.util.Map;
-import java.util.Set;
 import java.util.UUID;
-import java.util.stream.Collectors;
 
-public final class TelemetryHelper {
+/** A utility class for retrieving a unique client identifier (CLIENT_UID) */
+final class ClientIdentifier {
 
-  private TelemetryHelper() {} // Private constructor to prevent instantiation
+  private ClientIdentifier() {}
 
   private static String CLIENT_UID;
 
-  public static Map<InstrumentSelector, View> getAllViews() {
-    ImmutableMap.Builder<InstrumentSelector, View> views = ImmutableMap.builder();
-    gaxMetrics.forEach(metric -> defineView(views, metric, GAX_METER_NAME));
-    firestoreMetrics.forEach(metric -> defineView(views, metric, FIRESTORE_METER_NAME));
-    return views.build();
-  }
-
-  public static void defineView(
-      ImmutableMap.Builder<InstrumentSelector, View> viewMap, String id, String meter) {
-    InstrumentSelector selector =
-        InstrumentSelector.builder().setMeterName(meter).setName(METRIC_PREFIX + "/" + id).build();
-    Set<String> attributesFilter =
-        ImmutableSet.<String>builder()
-            .addAll(
-                COMMON_ATTRIBUTES.stream().map(AttributeKey::getKey).collect(Collectors.toSet()))
-            .build();
-    View view = View.builder().setAttributeFilter(attributesFilter).build();
-
-    viewMap.put(selector, view);
-  }
-
+  /** Gets the unique identifier for the client. */
   public static String getClientUid() {
     if (CLIENT_UID == null) {
       CLIENT_UID = generateClientUid();
     }
     return CLIENT_UID;
   }
 
+  /**
+   * Generates a unique identifier for the client that is composed of a random UUID, the process ID,
+   * and the hostname of the machine.
+   */
   private static String generateClientUid() {
     String identifier = UUID.randomUUID().toString();
     String pid = getProcessId();

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

@@ -20,6 +20,10 @@
 import com.google.api.gax.tracing.ApiTracerFactory;
 import java.util.List;
 
+/**
+ * A fully disabled (No-op) MetricsUtil class that does not perform any metrics collection actions
+ * and has near-zero overhead.
+ */
 class DisabledMetricsUtil implements MetricsUtil {
 
   class MetricsContext implements MetricsUtil.MetricsContext {

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

@@ -24,7 +24,7 @@
 import javax.annotation.Nullable;
 
 /**
- * A fully disabled (No-op) tracing utility class that does not perform any tracing actions and has
+ * A no-op implementation of {@link MetricsUtil} that does not collect or export any metrics and has
  * near-zero overhead.
  */
 public class DisabledTraceUtil implements TraceUtil {

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

@@ -16,8 +16,14 @@
 
 package com.google.cloud.firestore.telemetry;
 
+import static com.google.cloud.firestore.telemetry.TelemetryConstants.COMMON_ATTRIBUTES;
+import static com.google.cloud.firestore.telemetry.TelemetryConstants.FIRESTORE_METER_NAME;
+import static com.google.cloud.firestore.telemetry.TelemetryConstants.FIRESTORE_METRICS;
+import static com.google.cloud.firestore.telemetry.TelemetryConstants.GAX_METER_NAME;
+import static com.google.cloud.firestore.telemetry.TelemetryConstants.GAX_METRICS;
 import static com.google.cloud.firestore.telemetry.TelemetryConstants.METRIC_KEY_METHOD;
 import static com.google.cloud.firestore.telemetry.TelemetryConstants.METRIC_KEY_STATUS;
+import static com.google.cloud.firestore.telemetry.TelemetryConstants.METRIC_PREFIX;
 
 import com.google.api.core.ApiFuture;
 import com.google.api.core.ApiFutureCallback;
@@ -29,10 +35,13 @@
 import com.google.cloud.opentelemetry.metric.GoogleCloudMetricExporter;
 import com.google.cloud.opentelemetry.metric.MetricConfiguration;
 import com.google.common.base.Stopwatch;
+import com.google.common.collect.ImmutableMap;
+import com.google.common.collect.ImmutableSet;
 import com.google.common.util.concurrent.MoreExecutors;
 import io.grpc.Status;
 import io.opentelemetry.api.GlobalOpenTelemetry;
 import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.api.common.AttributeKey;
 import io.opentelemetry.sdk.OpenTelemetrySdk;
 import io.opentelemetry.sdk.metrics.InstrumentSelector;
 import io.opentelemetry.sdk.metrics.SdkMeterProvider;
@@ -44,10 +53,16 @@
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import java.util.concurrent.TimeUnit;
 import java.util.logging.Logger;
+import java.util.stream.Collectors;
 import javax.annotation.Nullable;
 
+/**
+ * An implementation of {@link MetricsUtil} that uses OpenTelemetry to collect and export metrics.
+ * `FirestoreOpenTelemetryOptions` in `FirestoreOptions` can be used to configure its behavior.
+ */
 class EnabledMetricsUtil implements MetricsUtil {
   private BuiltinMetricsProvider defaultMetricsProvider;
   private BuiltinMetricsProvider customMetricsProvider;
@@ -73,11 +88,26 @@ class EnabledMetricsUtil implements MetricsUtil {
     }
   }
 
+  @Override
+  public MetricsContext createMetricsContext(String methodName) {
+    return new MetricsContext(methodName);
+  }
+
+  @Override
+  public void addMetricsTracerFactory(List<ApiTracerFactory> apiTracerFactories) {
+    addTracerFactory(apiTracerFactories, defaultMetricsProvider);
+    addTracerFactory(apiTracerFactories, customMetricsProvider);
+  }
+
+  /**
+   * Creates a default {@link OpenTelemetry} instance to collect and export built-in client side
+   * metrics to Google Cloud Monitoring.
+   */
   private OpenTelemetry getDefaultOpenTelemetryInstance(String projectId) throws IOException {
     SdkMeterProviderBuilder sdkMeterProviderBuilder = SdkMeterProvider.builder();
 
     // Filter out attributes that are not defined
-    for (Map.Entry<InstrumentSelector, View> entry : TelemetryHelper.getAllViews().entrySet()) {
+    for (Map.Entry<InstrumentSelector, View> entry : getAllViews().entrySet()) {
       sdkMeterProviderBuilder.registerView(entry.getKey(), entry.getValue());
     }
 
@@ -107,15 +137,25 @@ private OpenTelemetry getDefaultOpenTelemetryInstance(String projectId) throws I
     return OpenTelemetrySdk.builder().setMeterProvider(sdkMeterProviderBuilder.build()).build();
   }
 
-  @Override
-  public MetricsContext createMetricsContext(String methodName) {
-    return new MetricsContext(methodName);
+  private static Map<InstrumentSelector, View> getAllViews() {
+    ImmutableMap.Builder<InstrumentSelector, View> views = ImmutableMap.builder();
+    GAX_METRICS.forEach(metric -> defineView(views, metric, GAX_METER_NAME));
+    FIRESTORE_METRICS.forEach(metric -> defineView(views, metric, FIRESTORE_METER_NAME));
+    return views.build();
   }
 
-  @Override
-  public void addMetricsTracerFactory(List<ApiTracerFactory> apiTracerFactories) {
-    addTracerFactory(apiTracerFactories, defaultMetricsProvider);
-    addTracerFactory(apiTracerFactories, customMetricsProvider);
+  private static void defineView(
+      ImmutableMap.Builder<InstrumentSelector, View> viewMap, String id, String meter) {
+    InstrumentSelector selector =
+        InstrumentSelector.builder().setMeterName(meter).setName(METRIC_PREFIX + "/" + id).build();
+    Set<String> attributesFilter =
+        ImmutableSet.<String>builder()
+            .addAll(
+                COMMON_ATTRIBUTES.stream().map(AttributeKey::getKey).collect(Collectors.toSet()))
+            .build();
+    View view = View.builder().setAttributeFilter(attributesFilter).build();
+
+    viewMap.put(selector, view);
   }
 
   private void addTracerFactory(
@@ -160,28 +200,27 @@ public void recordEndToEndLatency(Throwable t) {
       recordEndToEndLatency(extractErrorStatus(t));
     }
 
-    private void recordEndToEndLatency(String status) {
-      double elapsedTime = stopwatch.elapsed(TimeUnit.MILLISECONDS);
-      Map<String, String> attributes = createAttributes(status);
-      defaultMetricsProvider.endToEndRequestLatencyRecorder(elapsedTime, attributes);
-      customMetricsProvider.endToEndRequestLatencyRecorder(elapsedTime, attributes);
-    }
-
     public void recordFirstResponseLatency() {
       double elapsedTime = stopwatch.elapsed(TimeUnit.MILLISECONDS);
       Map<String, String> attributes = createAttributes(StatusCode.Code.OK.toString());
       defaultMetricsProvider.firstResponseLatencyRecorder(elapsedTime, attributes);
       customMetricsProvider.firstResponseLatencyRecorder(elapsedTime, attributes);
     }
 
+    private void recordEndToEndLatency(String status) {
+      double elapsedTime = stopwatch.elapsed(TimeUnit.MILLISECONDS);
+      Map<String, String> attributes = createAttributes(status);
+      defaultMetricsProvider.endToEndRequestLatencyRecorder(elapsedTime, attributes);
+      customMetricsProvider.endToEndRequestLatencyRecorder(elapsedTime, attributes);
+    }
+
     private Map<String, String> createAttributes(String status) {
       Map<String, String> attributes = new HashMap<>();
-      attributes.put(METRIC_KEY_METHOD.toString(), methodName);
-      attributes.put(METRIC_KEY_STATUS.toString(), status);
+      attributes.put(METRIC_KEY_METHOD.getKey(), methodName);
+      attributes.put(METRIC_KEY_STATUS.getKey(), status);
       return attributes;
     }
 
-    /** Function to extract the status of the error as a string */
     private String extractErrorStatus(@Nullable Throwable throwable) {
       if (!(throwable instanceof FirestoreException)) {
         return StatusCode.Code.UNKNOWN.toString();