[nidhiii-27]

Description

This PR implements Phase 2 (Configuration & Options API) of the OpenTelemetry Client Metrics feature in the Java Cloud Storage SDK (google-cloud-storage), building on top of PR #14398 (feat/storage-client-metrics-infra).

Key Changes

1. Public Options API (StorageOptions, GrpcStorageOptions, HttpStorageOptions):

   • Added configuration methods for OpenTelemetry metrics:
     • isEnableOtelMetrics() (default: false)
     • isEnableOtelDebugMetrics() (default: false)
     • getMeterProvider() returning io.opentelemetry.api.metrics.MeterProvider (from opentelemetry-api, avoiding leaking SDK implementation types in public API surface)
     • getMetricInterval() (default: 60 seconds; clamped to 60 seconds when using default Cloud Monitoring exporter)
   • Added builder setters annotated with @BetaApi:
     • setEnableOtelMetrics(boolean)
     • setEnableOtelDebugMetrics(boolean)
     • setMeterProvider(MeterProvider)
     • setMetricInterval(Duration) with precondition check requiring positive, non-zero durations (and >= 60 seconds unless a custom MeterProvider or OpenTelemetry is configured).

2. Feature Gates & Environment Variables (StorageMetricsConfig):

   • Environment variable gates:
     • GCP_STORAGE_JAVA_ENABLE_OTEL_METRICS
     • GCP_STORAGE_JAVA_ENABLE_OTEL_DEBUG_METRICS
   • Priority resolution: programmatic builder configuration > environment variable > default (false).
   • Case-insensitive boolean parsing matching cross-language SDK standard (1/t/true and 0/f/false).

3. Serialization Resiliency for Distributed Runtimes:

   • For distributed worker environments (Apache Spark, Apache Beam, Google Cloud Dataflow) where StorageOptions is serialized across worker nodes:
     • Defined meterProvider as transient (non-serializable).
     • Logged a one-time warning in readObject() when deserializing an instance configured with a custom MeterProvider, indicating fallback to the default provider.
     • In getMetricInterval(), clamped interval to minimum 60 seconds if meterProvider == null && !customOpenTelemetryConfigured to ensure compatibility with Cloud Monitoring.

4. Testing:

   • Added comprehensive tests in StorageOptionsTest:
     • Environment variable gating precedence.
     • Builder validation asserting IllegalArgumentException on null, zero, negative, or invalid (< 60s without custom provider) metric intervals.
     • Roundtrip serialization/deserialization verification (ByteArrayOutputStream / ObjectInputStream) ensuring transient meterProvider handling, fallback defaults, and interval clamping post-deserialization.

[Generated-by: AI]

[gemini-code-assist]

Code Review

This pull request introduces OpenTelemetry client metrics configuration across GrpcStorageOptions, HttpStorageOptions, and StorageOptions, supported by a new StorageMetricsConfig class and comprehensive unit tests. The review feedback highlights critical issues regarding backward compatibility during deserialization, where the newly added metricInterval field could be null and cause a NullPointerException, and recommends declaring the static resolvers in StorageMetricsConfig as volatile to ensure thread safety during parallel test execution.

[cpriti-os]

Requesting changes mainly for serialization behaviour and the enablement configuration (see inline comments).

[cpriti-os]

Thanks for addressing all the previous comments!

[cpriti-os]

LGTM once the getMeterProvider() default behavior below is addressed.

[Dhriti07]

Suggestion: We repeat the same test cases for both HttpStorageOptions and GrpcStorageOptions across most of StorageOptionsTest. Could we deduplicate these via a small helper or parameterization to reduce duplication across code. This prevents copy-paste drift between HTTP and gRPC and makes future test maintenance easier.