feat(storage): OpenTelemetry client metrics instrument registry and views by nidhiii-27 · Pull Request #14398 · googleapis/google-cloud-java

nidhiii-27 · 2026-09-16T09:21:44Z

This PR implements Phase 1 (Core Metrics Registry & Views) of the OpenTelemetry Client Metrics feature in the Java Cloud Storage SDK (google-cloud-storage).

Following review feedback and architectural alignment with other Storage SDKs, this PR focuses strictly on the package-private instrument registry and OpenTelemetry view/histogram boundary bootstrapping, decoupling it from public options and configuration APIs (split into companion follow-up PR #14484).

Key Changes

Instrument Registry (`StorageClientMetrics`)

Created package-private instrument registry holding standard and debug OpenTelemetry instruments.
Standard metrics:
- rpc.client.call.duration (s)
- http.client.request.duration (s)
- gcp.client.request.duration (s)
- gcp.storage.client.operations (1)
- gcp.storage.client.attempts (1)
- gcp.storage.client.errors (1)
- gcp.storage.client.operation.ttfb (s)
- gcp.storage.client.request.body.size (By)
- gcp.storage.client.response.body.size (By)
Advanced / Debug metrics:
- gcp.storage.client.request.active (1)
- gcp.storage.client.gfe.duration (s)
- gcp.storage.client.gfe.header_missing (1)
- gcp.storage.client.stall.duration (s)
- gcp.storage.client.network.bytes.sent (By)
- gcp.storage.client.network.bytes.received (By)
- gcp.storage.client.auth.credential_refresh.duration (s)
Documented connection-level metrics (dns.lookup.duration, tcp.connect.duration, tls.handshake.duration) as deferred placeholders.
Fixed description typo: "Retries not included".

OpenTelemetry Bootstrapping (`OpenTelemetryBootstrappingUtils`)

Registered custom explicit bucket histogram boundaries for client metrics:
- CLIENT_LATENCY_HISTOGRAMS using 2ms-resolution exponential buckets.
- CLIENT_SIZE_HISTOGRAMS using 128KiB to 16GiB buckets.
Added createClientMeterProvider with storage.googleapis.com/Client monitored resource.

Testing

Added opentelemetry-sdk-testing to pom.xml.
Added comprehensive tests in StorageClientMetricsTest verifying instrument registration and custom view boundaries via InMemoryMetricReader.
Verified boundary distributions in OpenTelemetryBootstrappingUtilsTest.

[Generated-by: AI]

…nfiguration - Add configuration options to StorageOptions, GrpcStorageOptions, and HttpStorageOptions (enableOtelMetrics, enableOtelDebugMetrics, meterProvider, metricInterval). - Add development gate checking system properties and environment variables in StorageMetricsConfig. - Implement package-private instrument registry in StorageClientMetrics. - Update OpenTelemetryBootstrappingUtils to register client views with custom histogram boundaries and create client meter provider. - Add comprehensive unit tests in StorageOptionsTest, StorageClientMetricsTest, and OpenTelemetryBootstrappingUtilsTest.

gemini-code-assist

Code Review

This pull request introduces OpenTelemetry client metrics support for Google Cloud Storage, allowing standard and debug metrics to be configured and recorded for both HTTP and gRPC transports. It adds configuration options to StorageOptions, GrpcStorageOptions, and HttpStorageOptions for enabling metrics, setting custom meter providers, and defining export intervals, supported by a new StorageMetricsConfig utility and StorageClientMetrics registry. Feedback on the changes suggests importing java.time.Duration to avoid using fully qualified class names throughout GrpcStorageOptions.java and OpenTelemetryBootstrappingUtils.java, which will improve code readability and consistency.

Apply spotify fmt-maven-plugin formatting to StorageMetricsConfig, StorageClientMetrics, StorageOptionsTest, and StorageClientMetricsTest. [Generated-by: AI]

Use simple class name Duration instead of fully qualified java.time.Duration in GrpcStorageOptions and OpenTelemetryBootstrappingUtils. [Generated-by: AI]

…trappingUtils Apply spotify fmt-maven-plugin formatting to OpenTelemetryBootstrappingUtils. [Generated-by: AI]

…nd views [Generated-by: AI]

… metrics Refactor addClientHistogramView in OpenTelemetryBootstrappingUtils to remove unit selector and custom view description, preserving instrument default descriptions. Remove deferred Phase 2 connection metrics (dnsLookupDuration, tcpConnectDuration, tlsHandshakeDuration) from StorageClientMetrics, CLIENT_LATENCY_HISTOGRAMS, and StorageClientMetricsTest. Ensure clean Duration imports. [Generated-by: AI]

…rProvider Default api parameter to "grpc" instead of "storage" in createClientMeterProvider, allow specifying "json" / "http" transport protocols for Cloud Monitoring monitored resource storage.googleapis.com/Client, and add unit test coverage in OpenTelemetryBootstrappingUtilsTest. [Generated-by: AI]

cpriti-os

Requesting changes mainly for the metric types/names and for accuracy of the recorded data (see inline comments).

One question on the overall design: createMeterProvider is only reached from enableGrpcMetrics(). Please state in the PR description how metrics are exported for HttpStorageOptions when metrics are enabled and no MeterProvider is supplied; both transports are expected to export through the same SDK-owned provider.

cpriti-os

Thanks for addressing the previous comments! Left a few small updates from our latest metrics/attributes alignment.

cpriti-os · 2026-10-13T12:27:55Z

+  static final AttributeKey<String> KEY_GCP_CLIENT_ARTIFACT =
+      AttributeKey.stringKey("gcp.client.artifact");
+  static final AttributeKey<String> KEY_GCP_CLIENT_INSTANCE_ID =
+      AttributeKey.stringKey("gcp.client.instance_id");


Could we also define the AttributeKey constants for the metric attributes here so the instrumentation PRs can share them? Specifically: gcp.storage.operation, gcp.client.method, rpc.method, rpc.system.name, rpc.response.status_code (string status name, replacing rpc.grpc.status_code), http.request.method, http.response.status_code, server.address, server.port, error.type, network.path ("directpath", "cloudpath", "unknown"), and network.io.direction ("receive", "transmit").

cpriti-os · 2026-10-13T12:27:55Z

+  static final String METRIC_GCP_STORAGE_CLIENT_OPERATIONS = "gcp.storage.client.operations";
+  static final String METRIC_GCP_STORAGE_CLIENT_ATTEMPTS = "gcp.storage.client.attempts";
+  static final String METRIC_GCP_STORAGE_CLIENT_ERRORS = "gcp.storage.client.errors";
+  static final String METRIC_GCP_STORAGE_CLIENT_OPERATION_TTFB =


We added a 10th standard metric gcp.storage.client.retries (LongCounter, unit "1", description "Number of GCS client retry attempts."). Could you add METRIC_GCP_STORAGE_CLIENT_RETRIES here as well?

cpriti-os · 2026-10-13T12:27:55Z

+  static final String METRIC_GCP_STORAGE_CLIENT_ATTEMPTS = "gcp.storage.client.attempts";
+  static final String METRIC_GCP_STORAGE_CLIENT_ERRORS = "gcp.storage.client.errors";
+  static final String METRIC_GCP_STORAGE_CLIENT_OPERATION_TTFB =
+      "gcp.storage.client.operation.ttfb";


Please rename gcp.storage.client.operation.ttfb to gcp.storage.client.ttfb (METRIC_GCP_STORAGE_CLIENT_TTFB, getTtfb()) here and in CLIENT_LATENCY_HISTOGRAMS to match Go and the Monarch descriptor (since TTFB is per-attempt, not per-operation).

cpriti-os · 2026-10-13T12:27:55Z

+        meter
+            .histogramBuilder(METRIC_RPC_CLIENT_CALL_DURATION)
+            .setDescription("Duration of one gRPC request. Retries not included (Otel)")
+            .setUnit("s")


nit: Can we drop "(Otel)" from the rpc.client.call.duration and http.client.request.duration descriptions (e.g. "Duration of a single gRPC client call attempt to Cloud Storage." / "Duration of a single HTTP request attempt to Cloud Storage." )?

cpriti-os · 2026-10-13T12:39:57Z

+  private final Attributes clientAttributes;
+
+  static StorageClientMetrics create(MeterProvider meterProvider, boolean enableOtelDebugMetrics) {
+    return create(meterProvider, UUID.randomUUID().toString(), enableOtelDebugMetrics);


enableOtelMetrics and enableOtelDebugMetrics should work independently (so setting enableOtelMetrics = false and enableOtelDebugMetrics = true initializes only the debug instruments and leaves the standard instruments null). Could we pass both boolean enableOtelMetrics, boolean enableOtelDebugMetrics into StorageClientMetrics.create(...) and gate the standard instruments on enableOtelMetrics?

nidhiii-27 requested review from a team as code owners September 16, 2026 09:21

gemini-code-assist Bot reviewed Sep 16, 2026

View reviewed changes

nidhiii-27 added 3 commits September 16, 2026 09:46

fix(storage): resolve code formatting violations for client metrics

f5fc3fe

Apply spotify fmt-maven-plugin formatting to StorageMetricsConfig, StorageClientMetrics, StorageOptionsTest, and StorageClientMetricsTest. [Generated-by: AI]

fix(storage): resolve PR review comments on OpenTelemetry metrics

957061c

Use simple class name Duration instead of fully qualified java.time.Duration in GrpcStorageOptions and OpenTelemetryBootstrappingUtils. [Generated-by: AI]

fix(storage): resolve code formatting violation in OpenTelemetryBoots…

f05341f

…trappingUtils Apply spotify fmt-maven-plugin formatting to OpenTelemetryBootstrappingUtils. [Generated-by: AI]

nidhiii-27 added the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Sep 16, 2026

yoshi-kokoro removed the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Sep 16, 2026

feat(storage): add OpenTelemetry client metrics instrument registry a…

b18e729

…nd views [Generated-by: AI]

nidhiii-27 changed the title ~~feat(storage): OpenTelemetry client metrics infrastructure and configuration~~ feat(storage): OpenTelemetry client metrics instrument registry and views Sep 23, 2026

nidhiii-27 mentioned this pull request Sep 23, 2026

feat(storage): OpenTelemetry client metrics configuration and options #14484

Open

nidhiii-27 added the ai-generated label Sep 23, 2026

nidhiii-27 added this pull request to stack #14485 September 23, 2026 10:36

nidhiii-27 added 2 commits September 30, 2026 06:27

nidhiii-27 added the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Oct 7, 2026

yoshi-kokoro removed the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Oct 7, 2026

cpriti-os requested changes Oct 7, 2026

View reviewed changes

fix(storage): address review comments for OpenTelemetry client metrics

9727288

nidhiii-27 requested a review from cpriti-os October 8, 2026 07:29

cpriti-os reviewed Oct 13, 2026

View reviewed changes

cpriti-os approved these changes Oct 13, 2026

View reviewed changes

cpriti-os reviewed Oct 13, 2026

View reviewed changes

Conversation

nidhiii-27 commented Sep 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Key Changes

Instrument Registry (StorageClientMetrics)

OpenTelemetry Bootstrapping (OpenTelemetryBootstrappingUtils)

Testing

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cpriti-os left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cpriti-os left a comment

Choose a reason for hiding this comment

Uh oh!

cpriti-os Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

cpriti-os Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

cpriti-os Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

cpriti-os Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

cpriti-os Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

nidhiii-27 commented Sep 16, 2026 •

edited

Loading

Instrument Registry (`StorageClientMetrics`)

OpenTelemetry Bootstrapping (`OpenTelemetryBootstrappingUtils`)

cpriti-os left a comment •

edited

Loading