feat(storage): add StorageMetricsContext and StorageErrorTypeMapper for standard metrics

[nidhiii-27]

Description

This PR implements PR 1 of the Standard Metrics phase for the Google Cloud Storage Java SDK (google-cloud-java), based on the O11y 2026 High Level Design (HLD) and Java Low Level Design (LLD).

It introduces the foundation for context propagation and canonical error mapping:

1. StorageMetricsContext:
   • Package-private holder for operation metric state across asynchronous and thread-hopping boundaries (such as ApiFuture callbacks and thread pools).
   • Tracks operationName, startTimeNanos, attemptCount, user-facing requestBytes and responseBytes, and base OTel Attributes.
   • Supports transport context attachment and extraction for gRPC CallOptions/GrpcCallContext/ApiCallContext and HTTP property maps.
2. StorageErrorTypeMapper:
   • Centralized package-private utility mapping exceptions and status codes to uppercase canonical status strings per O11y 2026 specifications.
   • Maps gRPC status codes (NOT_FOUND, UNAVAILABLE, DEADLINE_EXCEEDED -> TIMEOUT, etc.).
   • Maps HTTP response codes (2xx -> OK, 400 -> INVALID_ARGUMENT, 401 -> AUTHENTICATION_ERROR, 403 -> PERMISSION_DENIED, 404 -> NOT_FOUND, 409 -> ALREADY_EXISTS, 412 -> FAILED_PRECONDITION, 429 -> RESOURCE_EXHAUSTED, 500 -> INTERNAL, 503 -> UNAVAILABLE, 504 -> TIMEOUT, etc.).
   • Maps network/socket/TLS failures (SocketTimeoutException -> TIMEOUT, UnknownHostException -> DNS_FAILURE, ConnectException -> CONNECTION_REFUSED, SocketException -> CONNECTION_RESET, SSLHandshakeException -> TLS_FAILURE, generic IOException -> CONNECTIVITY, CancellationException -> CANCELLED).
   • Maps authentication exceptions (AUTHENTICATION_ERROR) and checksum mismatches (CHECKSUM_MISMATCH).
3. Unit Tests:
   • Comprehensive test coverage in StorageErrorTypeMapperTest and StorageMetricsContextTest.

Verification

• mvn com.spotify.fmt:fmt-maven-plugin:check -pl java-storage/google-cloud-storage (0 non-complying files)
• mvn checkstyle:check@checkstyle -pl java-storage/google-cloud-storage (0 violations)
• mvn test -pl java-storage/google-cloud-storage -Dtest=StorageErrorTypeMapperTest,StorageMetricsContextTest,StorageClientMetricsTest,StorageOptionsTest (39 tests run, 0 failures, 0 errors)

[gemini-code-assist]

Code Review

This pull request introduces comprehensive support for OpenTelemetry client metrics and debug metrics in Google Cloud Storage, including configuration options in StorageOptions, GrpcStorageOptions, and HttpStorageOptions. It adds utility classes such as StorageClientMetrics for instrument registration, StorageErrorTypeMapper for mapping exceptions to canonical error strings, StorageMetricsConfig for environment-based configuration, and StorageMetricsContext for tracking metric state across boundaries, along with corresponding unit tests. Feedback on the changes suggests simplifying a redundant null check on a transient field in StorageOptions, defensively preventing infinite loops from self-causation in StorageErrorTypeMapper's exception unwrapping, and robustly checking for authentication exceptions by using full class names instead of simple names to correctly handle anonymous classes.

I am having trouble creating individual review comments. Click here to see my feedback.

java-storage/google-cloud-storage/src/main/java/com/google/cloud/storage/StorageOptions.java (262)

Since meterProvider is marked as transient, it will not be serialized and will always be null after deserialization. Therefore, the check this.meterProvider != null in readObject is redundant and will always evaluate to false. We can simplify this to only check this.customMeterProviderConfigured.

    if (this.customMeterProviderConfigured) {

java-storage/google-cloud-storage/src/main/java/com/google/cloud/storage/StorageErrorTypeMapper.java (159-162)

To prevent potential infinite loops in case of custom exceptions with self-causation (where t.getCause() == t), we should defensively add a check for t.getCause() != t in the while loop condition, similar to how it is handled at the end of the mapThrowable method.

    while ((t instanceof ExecutionException || t instanceof CompletionException)
        && t.getCause() != null
        && t.getCause() != t) {
      t = t.getCause();
    }

java-storage/google-cloud-storage/src/main/java/com/google/cloud/storage/StorageErrorTypeMapper.java (258)

Using t.getClass().getSimpleName() can return an empty string "" for anonymous classes, which would bypass the contains("Auth") check even if the base class name contains "Auth". Using the full class name className.contains("Auth") is more robust and avoids extra string parsing overhead.

    if (className.contains("Auth")) {

[cpriti-os]

Two small mapping fixes:

• HTTP 401 should map to "UNAUTHENTICATED" (matching gRPC Status.UNAUTHENTICATED), while "AUTHENTICATION_ERROR" is for client-side token refresh/auth exceptions.
• HTTP 502 should also map to "UNAVAILABLE" alongside 503.

[nidhiii-27]

Done

Co-authored by AI Agent