feat(datastore): Add built-in Cloud Monitoring metrics export

Add a default-on, private OpenTelemetry SDK pipeline that automatically
exports Datastore client-side metrics to Google Cloud Monitoring without
requiring any user configuration.

Key additions:
- DatastoreBuiltInMetricsView: registers OTel views for metric renaming
  (GAX prefix → custom.googleapis.com/internal/client), custom histogram
  bucket boundaries, and an attribute allowlist that prevents unexpected
  labels from reaching Cloud Monitoring
- DatastoreCloudMonitoringExporter: MetricExporter impl that batches
  TimeSeries and calls MetricServiceClient.createTimeSeries(); graceful
  degradation (logs warnings, never crashes); best-effort flush()
- DatastoreCloudMonitoringExporterUtils: converts OTel MetricData to
  Cloud Monitoring TimeSeries protos
- BuiltInDatastoreMetricsProvider: creates a private OpenTelemetrySdk
  per Datastore client; computes stable client_uid and client_name
  attributes; registers a shutdown hook as a last-resort safety net
- CompositeDatastoreMetricsRecorder: fans out all record*() calls to
  both the built-in and any user-provided backends simultaneously
- DatastoreMetricsRecorder.getInstance(): updated to composite factory
  that wires up the built-in path (unless emulator or env-var disabled)
  alongside any custom OTel backend; adds default close() for lifecycle
- OpenTelemetryDatastoreMetricsRecorder: add ownsOpenTelemetry flag and
  close() so the built-in SDK is flushed when DatastoreImpl.close() runs
- DatastoreOpenTelemetryOptions: add exportBuiltinMetricsToGoogleCloudMonitoring
  flag (default true) with @BetaApi getter and setter; clarify isEnabled()
  Javadoc to note it does not cover the built-in path
- DatastoreImpl.close(): call getMetricsRecorder().close() after RPC
  channel teardown so the built-in SDK flushes buffered metrics
- pom.xml: promote opentelemetry-sdk, opentelemetry-sdk-common, and
  opentelemetry-sdk-metrics from test→compile scope; add
  google-cloud-monitoring and proto-google-cloud-monitoring-v3 compile deps
- New tests: DatastoreCloudMonitoringExporterTest, BuiltInDatastoreMetricsProviderTest,
  DatastoreMetricsRecorderTest (updated), DatastoreBuiltInAndCustomMetricsIT

Author: lqiu96

java-datastore/google-cloud-datastore/pom.xml

@@ -196,12 +196,20 @@
     <dependency>
       <groupId>io.opentelemetry</groupId>
       <artifactId>opentelemetry-sdk</artifactId>
-      <scope>test</scope>
     </dependency>
     <dependency>
       <groupId>io.opentelemetry</groupId>
       <artifactId>opentelemetry-sdk-common</artifactId>
-      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>com.google.cloud</groupId>
+      <artifactId>google-cloud-monitoring</artifactId>
+      <version>3.90.0-SNAPSHOT</version><!-- {x-version-update:google-cloud-monitoring:current} -->
+    </dependency>
+    <dependency>
+      <groupId>com.google.api.grpc</groupId>
+      <artifactId>proto-google-cloud-monitoring-v3</artifactId>
+      <version>3.90.0-SNAPSHOT</version><!-- {x-version-update:google-cloud-monitoring:current} -->
     </dependency>
     <dependency>
       <groupId>io.opentelemetry</groupId>
@@ -216,7 +224,6 @@
     <dependency>
       <groupId>io.opentelemetry</groupId>
       <artifactId>opentelemetry-sdk-metrics</artifactId>
-      <scope>test</scope>
     </dependency>
     <dependency>
       <groupId>io.opentelemetry</groupId>

java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreImpl.java

@@ -162,13 +162,24 @@ public T call() throws DatastoreException {
     }
   }
 
+  /**
+   * Closes the Datastore client and releases all resources.
+   *
+   * <p>This method closes the underlying RPC channel and then closes the {@link
+   * com.google.cloud.datastore.telemetry.DatastoreMetricsRecorder}. For clients using the
+   * built-in Cloud Monitoring exporter, closing the recorder flushes any buffered metrics and
+   * shuts down the private {@link io.opentelemetry.sdk.OpenTelemetrySdk} instance. For clients
+   * using a user-provided {@link io.opentelemetry.api.OpenTelemetry} instance, the recorder close
+   * is a no-op since the user owns that instance's lifecycle.
+   */
   @Override
   public void close() throws Exception {
     try {
       datastoreRpc.close();
     } catch (Exception e) {
       logger.log(Level.WARNING, "Failed to close channels", e);
     }
+    getOptions().getMetricsRecorder().close();
   }
 
   @Override

java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreOpenTelemetryOptions.java

@@ -16,25 +16,39 @@
 
 package com.google.cloud.datastore;
 
+import com.google.api.core.BetaApi;
 import io.opentelemetry.api.OpenTelemetry;
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
+/**
+ * Represents the options that are used to configure the use of OpenTelemetry for telemetry
+ * collection in the Datastore SDK.
+ */
 public class DatastoreOpenTelemetryOptions {
   private final boolean tracingEnabled;
   private final boolean metricsEnabled;
+  private final boolean exportBuiltinMetricsToGoogleCloudMonitoring;
   private final @Nullable OpenTelemetry openTelemetry;
 
   DatastoreOpenTelemetryOptions(Builder builder) {
     this.tracingEnabled = builder.tracingEnabled;
     this.metricsEnabled = builder.metricsEnabled;
+    this.exportBuiltinMetricsToGoogleCloudMonitoring =
+        builder.exportBuiltinMetricsToGoogleCloudMonitoring;
     this.openTelemetry = builder.openTelemetry;
   }
 
   /**
-   * Returns whether either tracing or metrics are enabled. Telemetry is disabled by default.
+   * Returns whether either tracing or custom metrics (via a user-provided {@link OpenTelemetry}
+   * instance) are enabled.
+   *
+   * <p><b>Note:</b> This method does <em>not</em> reflect the state of built-in metrics export to
+   * Google Cloud Monitoring, which is controlled separately by {@link
+   * #isExportBuiltinMetricsToGoogleCloudMonitoring()} and is {@code true} by default. To check
+   * whether any telemetry is active, also consult that flag.
    *
-   * @return {@code true} if either tracing or metrics are enabled, {@code false} otherwise.
+   * @return {@code true} if tracing or custom OTel metrics are enabled, {@code false} otherwise.
    */
   public boolean isEnabled() {
     return tracingEnabled || metricsEnabled;
@@ -50,24 +64,54 @@ public boolean isTracingEnabled() {
   }
 
   /**
-   * Returns whether metrics are enabled.
+   * Returns whether metrics are enabled for the custom (user-provided) OpenTelemetry backend.
    *
    * @return {@code true} if metrics are enabled, {@code false} otherwise.
    */
   public boolean isMetricsEnabled() {
     return metricsEnabled;
   }
 
+  /**
+   * Returns whether built-in metrics should be exported to Google Cloud Monitoring.
+   *
+   * <p>When enabled, client-side metrics are automatically exported to Google Cloud Monitoring
+   * using the Cloud Monitoring API. This is independent of the custom OpenTelemetry backend
+   * configured via {@link #getOpenTelemetry()}.
+   *
+   * @return {@code true} if built-in metrics export to Cloud Monitoring is enabled, {@code false}
+   *     otherwise.
+   */
+  @BetaApi
+  public boolean isExportBuiltinMetricsToGoogleCloudMonitoring() {
+    return exportBuiltinMetricsToGoogleCloudMonitoring;
+  }
+
+  /**
+   * Returns the custom {@link OpenTelemetry} instance, if one was provided.
+   *
+   * @return the custom {@link OpenTelemetry} instance, or {@code null} if none was provided.
+   */
   @Nullable
   public OpenTelemetry getOpenTelemetry() {
     return openTelemetry;
   }
 
+  /**
+   * Returns a new {@link Builder} initialized with the values from this options instance.
+   *
+   * @return a new {@link Builder}.
+   */
   @Nonnull
   public DatastoreOpenTelemetryOptions.Builder toBuilder() {
     return new DatastoreOpenTelemetryOptions.Builder(this);
   }
 
+  /**
+   * Returns a new default {@link Builder}.
+   *
+   * @return a new {@link Builder}.
+   */
   @Nonnull
   public static DatastoreOpenTelemetryOptions.Builder newBuilder() {
     return new DatastoreOpenTelemetryOptions.Builder();
@@ -77,25 +121,30 @@ public static class Builder {
 
     private boolean tracingEnabled;
     private boolean metricsEnabled;
+    private boolean exportBuiltinMetricsToGoogleCloudMonitoring;
 
     @Nullable private OpenTelemetry openTelemetry;
 
     private Builder() {
       tracingEnabled = false;
       metricsEnabled = false;
+      exportBuiltinMetricsToGoogleCloudMonitoring = true;
       openTelemetry = null;
     }
 
     private Builder(DatastoreOpenTelemetryOptions options) {
       this.tracingEnabled = options.tracingEnabled;
       this.metricsEnabled = options.metricsEnabled;
+      this.exportBuiltinMetricsToGoogleCloudMonitoring =
+          options.exportBuiltinMetricsToGoogleCloudMonitoring;
       this.openTelemetry = options.openTelemetry;
     }
 
     /**
      * Sets whether tracing should be enabled.
      *
      * @param enabled Whether tracing should be enabled.
+     * @return this builder instance.
      */
     @Nonnull
     public DatastoreOpenTelemetryOptions.Builder setTracingEnabled(boolean enabled) {
@@ -104,23 +153,43 @@ public DatastoreOpenTelemetryOptions.Builder setTracingEnabled(boolean enabled)
     }
 
     /**
-     * Sets whether metrics should be enabled.
+     * Sets whether metrics should be enabled for the custom (user-provided) OpenTelemetry backend.
      *
      * @param enabled Whether metrics should be enabled.
-     * @return the builder instance.
+     * @return this builder instance.
      */
     @Nonnull
     DatastoreOpenTelemetryOptions.Builder setMetricsEnabled(boolean enabled) {
       this.metricsEnabled = enabled;
       return this;
     }
 
+    /**
+     * Sets whether built-in metrics should be exported to Google Cloud Monitoring.
+     *
+     * <p>When enabled (the default), client-side metrics are automatically exported to Google Cloud
+     * Monitoring using the Cloud Monitoring API. This can be disabled to prevent metrics from being
+     * sent to Cloud Monitoring while still allowing metrics to flow to a custom OpenTelemetry
+     * backend.
+     *
+     * @param exportBuiltinMetrics Whether built-in metrics should be exported to Cloud Monitoring.
+     * @return this builder instance.
+     */
+    @BetaApi
+    @Nonnull
+    public DatastoreOpenTelemetryOptions.Builder setExportBuiltinMetricsToGoogleCloudMonitoring(
+        boolean exportBuiltinMetrics) {
+      this.exportBuiltinMetricsToGoogleCloudMonitoring = exportBuiltinMetrics;
+      return this;
+    }
+
     /**
      * Sets the {@link OpenTelemetry} to use with this Datastore instance. If telemetry collection
-     * is enabled, but an `OpenTelemetry` is not provided, the Datastore SDK will attempt to use the
-     * `GlobalOpenTelemetry`.
+     * is enabled, but an {@code OpenTelemetry} is not provided, the Datastore SDK will attempt to
+     * use the {@code GlobalOpenTelemetry}.
      *
      * @param openTelemetry The OpenTelemetry that should be used by this Datastore instance.
+     * @return this builder instance.
      */
     @Nonnull
     public DatastoreOpenTelemetryOptions.Builder setOpenTelemetry(
@@ -129,6 +198,11 @@ public DatastoreOpenTelemetryOptions.Builder setOpenTelemetry(
       return this;
     }
 
+    /**
+     * Builds a new {@link DatastoreOpenTelemetryOptions} instance from this builder.
+     *
+     * @return a new {@link DatastoreOpenTelemetryOptions}.
+     */
     @Nonnull
     public DatastoreOpenTelemetryOptions build() {
       return new DatastoreOpenTelemetryOptions(this);