chore: Add implementation for firestore resource

Author: lqiu96

java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/telemetry/CompositeMetricsRecorder.java

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2026 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.datastore.telemetry;
+
+import java.util.List;
+import java.util.Map;
+
+/** A {@link MetricsRecorder} that fans out to multiple recorders. */
+class CompositeMetricsRecorder implements MetricsRecorder {
+
+  private final List<MetricsRecorder> recorders;
+
+  CompositeMetricsRecorder(List<MetricsRecorder> recorders) {
+    this.recorders = recorders;
+  }
+
+  @Override
+  public void recordTransactionLatency(double latencyMs, Map<String, String> attributes) {
+    for (MetricsRecorder recorder : recorders) {
+      recorder.recordTransactionLatency(latencyMs, attributes);
+    }
+  }
+
+  @Override
+  public void recordTransactionAttemptCount(long count, Map<String, String> attributes) {
+    for (MetricsRecorder recorder : recorders) {
+      recorder.recordTransactionAttemptCount(count, attributes);
+    }
+  }
+
+  @Override
+  public void recordAttemptLatency(double latencyMs, Map<String, String> attributes) {
+    for (MetricsRecorder recorder : recorders) {
+      recorder.recordAttemptLatency(latencyMs, attributes);
+    }
+  }
+
+  @Override
+  public void recordAttemptCount(long count, Map<String, String> attributes) {
+    for (MetricsRecorder recorder : recorders) {
+      recorder.recordAttemptCount(count, attributes);
+    }
+  }
+
+  @Override
+  public void recordOperationLatency(double latencyMs, Map<String, String> attributes) {
+    for (MetricsRecorder recorder : recorders) {
+      recorder.recordOperationLatency(latencyMs, attributes);
+    }
+  }
+
+  @Override
+  public void recordOperationCount(long count, Map<String, String> attributes) {
+    for (MetricsRecorder recorder : recorders) {
+      recorder.recordOperationCount(count, attributes);
+    }
+  }
+}

java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/telemetry/DatastoreBuiltInMetricsProvider.java

@@ -0,0 +1,271 @@
+/*
+ * Copyright 2026 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.datastore.telemetry;
+
+import com.google.api.gax.core.GaxProperties;
+import com.google.auth.Credentials;
+import com.google.common.base.Strings;
+import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.common.AttributesBuilder;
+import io.opentelemetry.sdk.metrics.SdkMeterProvider;
+import io.opentelemetry.sdk.metrics.SdkMeterProviderBuilder;
+import io.opentelemetry.sdk.resources.Resource;
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.lang.management.ManagementFactory;
+import java.lang.reflect.Method;
+import java.net.HttpURLConnection;
+import java.net.URL;
+import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+import javax.annotation.Nullable;
+
+/**
+ * Provides a built-in {@link OpenTelemetry} instance for Datastore client-side metrics.
+ *
+ * <p>This class is responsible for configuring a private {@link OpenTelemetrySdk} that exports
+ * metrics to Google Cloud Monitoring using a {@link DatastoreCloudMonitoringExporter}.
+ *
+ * <p>The implementation follows the pattern used in other Google Cloud client libraries, providing
+ * automated environment detection and resource attribute configuration for the {@code
+ * firestore.googleapis.com/Database} monitored resource.
+ */
+public final class DatastoreBuiltInMetricsProvider {
+
+  public static final DatastoreBuiltInMetricsProvider INSTANCE =
+      new DatastoreBuiltInMetricsProvider();
+
+  private static final Logger logger =
+      Logger.getLogger(DatastoreBuiltInMetricsProvider.class.getName());
+
+  private static String taskId;
+  private static String location;
+  private static final String DEFAULT_LOCATION = "global";
+
+  private SdkMeterProvider sdkMeterProvider;
+  private OpenTelemetry openTelemetry;
+
+  private DatastoreBuiltInMetricsProvider() {}
+
+  /**
+   * Returns a singleton {@link OpenTelemetry} instance for built-in metrics.
+   *
+   * <p>This method initializes an {@link SdkMeterProvider} with a {@link
+   * DatastoreCloudMonitoringExporter} and the appropriate resource attributes. It also registers a
+   * shutdown hook to ensure metrics are flushed when the JVM exits.
+   *
+   * @param projectId the GCP project ID.
+   * @param databaseId the Datastore database ID.
+   * @param credentials the credentials to use for exporting metrics.
+   * @param monitoringHost optional monitoring host override.
+   * @param universeDomain the universe domain to use for monitoring.
+   * @return the {@link OpenTelemetry} instance, or {@code null} if it could not be created.
+   */
+  public OpenTelemetry getOrCreateOpenTelemetry(
+      String projectId,
+      String databaseId,
+      @Nullable Credentials credentials,
+      @Nullable String monitoringHost,
+      String universeDomain) {
+    try {
+      if (this.openTelemetry == null) {
+        SdkMeterProviderBuilder sdkMeterProviderBuilder = SdkMeterProvider.builder();
+        // Register Datastore-specific views and the PeriodicMetricReader.
+        DatastoreBuiltInMetricsView.registerBuiltinMetrics(
+            DatastoreCloudMonitoringExporter.create(
+                projectId, credentials, monitoringHost, universeDomain),
+            sdkMeterProviderBuilder);
+        // Configure the monitored resource attributes.
+        sdkMeterProviderBuilder.setResource(
+            Resource.create(createResourceAttributes(projectId, databaseId)));
+        this.sdkMeterProvider = sdkMeterProviderBuilder.build();
+        this.openTelemetry = new DatastoreOpenTelemetry(this.sdkMeterProvider);
+        // Ensure cleanup on shutdown.
+        Runtime.getRuntime().addShutdownHook(new Thread(this.sdkMeterProvider::close));
+      }
+      return this.openTelemetry;
+    } catch (IOException ex) {
+      logger.log(
+          Level.WARNING,
+          "Unable to get OpenTelemetry object for client side metrics, will skip exporting client"
+              + " side metrics",
+          ex);
+      return null;
+    }
+  }
+
+  /**
+   * Quick check to see if the application is running on GCP by querying the metadata server.
+   *
+   * <p>This is used to determine if we should enable built-in metrics by default.
+   *
+   * @return {@code true} if running on GCP, {@code false} otherwise.
+   */
+  public static boolean quickCheckIsRunningOnGcp() {
+    int timeout = 5000;
+    try {
+      URL url = new URL("http://metadata.google.internal/computeMetadata/v1/project/project-id");
+      HttpURLConnection connection = (HttpURLConnection) url.openConnection();
+      connection.setConnectTimeout(timeout);
+      connection.setRequestProperty("Metadata-Flavor", "Google");
+      if (connection.getResponseCode() == 200
+          && ("Google").equals(connection.getHeaderField("Metadata-Flavor"))) {
+        InputStream input = connection.getInputStream();
+        try (BufferedReader reader =
+            new BufferedReader(new InputStreamReader(input, StandardCharsets.UTF_8))) {
+          return !Strings.isNullOrEmpty(reader.readLine());
+        }
+      }
+    } catch (IOException ignore) {
+      // ignore
+    }
+    return false;
+  }
+
+  /**
+   * Detects the client's GCP location (region).
+   *
+   * <p>To avoid dependencies on external resource detection libraries, this implementation
+   * currently defaults to "global".
+   *
+   * @return the detected location, or "global" if detection fails.
+   */
+  public static String detectClientLocation() {
+    if (location == null) {
+      location = DEFAULT_LOCATION;
+    }
+    return location;
+  }
+
+  /**
+   * Creates resource attributes for the {@code firestore.googleapis.com/Database} monitored
+   * resource.
+   *
+   * <p>These attributes are attached to the OTel {@link Resource} and used by the exporter to
+   * populate the resource labels in Cloud Monitoring.
+   *
+   * @param projectId the GCP project ID.
+   * @param databaseId the Datastore database ID.
+   * @return the resource attributes.
+   */
+  Attributes createResourceAttributes(String projectId, String databaseId) {
+    AttributesBuilder attributesBuilder =
+        Attributes.builder()
+            .put(TelemetryConstants.PROJECT_ID_KEY, projectId)
+            .put(TelemetryConstants.DATABASE_ID_KEY, databaseId)
+            .put(TelemetryConstants.LOCATION_ID_KEY, detectClientLocation());
+
+    return attributesBuilder.build();
+  }
+
+  /**
+   * Creates common client attributes for each metric data point.
+   *
+   * <p>These attributes (client_name, client_uid) are added to every exported metric to identify
+   * the specific client instance.
+   *
+   * @return a map of client attributes.
+   */
+  public Map<String, String> createClientAttributes() {
+    Map<String, String> clientAttributes = new HashMap<>();
+    clientAttributes.put(
+        TelemetryConstants.CLIENT_NAME_KEY.getKey(),
+        "datastore-java/" + GaxProperties.getLibraryVersion(getClass()));
+    clientAttributes.put(TelemetryConstants.CLIENT_UID_KEY.getKey(), getDefaultTaskValue());
+    clientAttributes.put(TelemetryConstants.SERVICE_KEY.getKey(), TelemetryConstants.SERVICE_VALUE);
+    return clientAttributes;
+  }
+
+  /**
+   * Generates a unique identifier for the {@code client_uid} metric field.
+   *
+   * <p>The identifier is composed of a UUID, the process ID (PID), and the hostname to ensure
+   * uniqueness across different instances and restarts.
+   *
+   * @return a unique identifier string in the format UUID@PID@hostname.
+   */
+  private static String getDefaultTaskValue() {
+    if (taskId == null) {
+      taskId = ManagementFactory.getRuntimeMXBean().getName();
+    }
+    return taskId;
+  }
+
+  /**
+   * Returns the process ID.
+   *
+   * <p>Attempts to use {@code ProcessHandle} (Java 9+) and falls back to {@code RuntimeMXBean} for
+   * Java 8 compatibility.
+   *
+   * @return the PID as a string.
+   */
+  private static String getProcessId() {
+    try {
+      // Check if Java 9+ and ProcessHandle class is available
+      Class<?> processHandleClass = Class.forName("java.lang.ProcessHandle");
+      Method currentMethod = processHandleClass.getMethod("current");
+      Object processHandleInstance = currentMethod.invoke(null);
+      Method pidMethod = processHandleClass.getMethod("pid");
+      long pid = (long) pidMethod.invoke(processHandleInstance);
+      return Long.toString(pid);
+    } catch (Exception e) {
+      // Fallback to Java 8 method
+      final String jvmName = ManagementFactory.getRuntimeMXBean().getName();
+      if (jvmName != null && jvmName.contains("@")) {
+        return jvmName.split("@")[0];
+      } else {
+        return "unknown";
+      }
+    }
+  }
+
+  /**
+   * A simple {@link OpenTelemetry} implementation that only provides a {@link
+   * io.opentelemetry.api.metrics.MeterProvider}.
+   *
+   * <p>This avoids a dependency on {@code OpenTelemetrySdk} and {@code SdkTracerProvider}, which
+   * are not needed for built-in metrics and might not be available on the classpath at runtime.
+   */
+  private static class DatastoreOpenTelemetry implements OpenTelemetry {
+    private final io.opentelemetry.api.metrics.MeterProvider meterProvider;
+
+    DatastoreOpenTelemetry(io.opentelemetry.api.metrics.MeterProvider meterProvider) {
+      this.meterProvider = meterProvider;
+    }
+
+    @Override
+    public io.opentelemetry.api.metrics.MeterProvider getMeterProvider() {
+      return meterProvider;
+    }
+
+    @Override
+    public io.opentelemetry.api.trace.TracerProvider getTracerProvider() {
+      return io.opentelemetry.api.trace.TracerProvider.noop();
+    }
+
+    @Override
+    public io.opentelemetry.context.propagation.ContextPropagators getPropagators() {
+      return io.opentelemetry.context.propagation.ContextPropagators.noop();
+    }
+  }
+}