[shradhakatyal]

Summary

Adds logical OpenTelemetry standard metrics instrumentation across Client, Bucket, Batch, ACL, HMACKeyMetadata, and BucketNotification JSON APIs in google-cloud-storage.

Stack Overview (review isolated commit 47160ae48f6 for this PR):

• Base: feat(storage): add OpenTelemetry standard metrics recorder, views, and helpers #18753 (feat/gcs-otel-standard-metrics)
• PR 2a: feat(storage): add OpenTelemetry standard metrics for HTTP JSON transport #18940 (feat/gcs-otel-http-transport-metrics)
• PR 2b: feat(storage): add OpenTelemetry standard metrics for Client, Bucket, and resource APIs #18941 (feat/gcs-otel-veneer-bucket-metrics) (this PR)
• PR 2c: feat(storage): add OpenTelemetry standard metrics for Blob JSON metadata APIs #18942 (feat/gcs-otel-veneer-blob-metrics)
• PR 3a: feat(storage): add OpenTelemetry standard metrics for HTTP media transfers #18943 (feat/gcs-otel-media-transport-metrics)
• PR 3b: feat(storage): add OpenTelemetry standard metrics for fileio and Blob.open streams #18944 (feat/gcs-otel-fileio-metrics)
• PR 3c: feat(storage): add OpenTelemetry standard metrics for transfer_manager #18945 (feat/gcs-otel-transfer-manager-metrics)

Key Changes

• Client & Bucket Operations (client.py, bucket.py): Instruments logical operations across bucket creation, lookup, metadata updates, IAM policies, lifecycle/retention helpers, and lazy HTTPIterator list APIs (ListBuckets, ListObjects, ListHmacKeys, ListNotifications).
• Batch Execution (batch.py): Records logical operation metrics on Batch.finish() while deferring queued sub-requests.
• Resource Classes (acl.py, hmac_key.py, notification.py): Instruments BucketACL, DefaultObjectACL, ObjectACL, HMACKeyMetadata, and BucketNotification CRUD operations.

[gemini-code-assist]

Code Review

This pull request introduces comprehensive OpenTelemetry standard metrics instrumentation across the Google Cloud Storage Python client, including route normalization, canonical error classification, and custom histogram views. It integrates metric recording into HTTP requests, bucket operations, ACLs, HMAC keys, and notifications, while adding extensive unit tests to verify transport and veneer metrics. The reviewer recommended wrapping attribute accesses in the exception chain traversal helper (_iter_exception_chain) with try...except blocks and logging any failures to prevent unexpected exceptions from propagating and masking original user exceptions.

[gemini-code-assist]

To prevent any unexpected exceptions during exception chain traversal from propagating and masking the original user exception, it is recommended to wrap the attribute accesses in try...except Exception blocks. However, avoid silently ignoring the exception with a broad except Exception: pass block. Instead, log the exception (e.g., using logger.warning) to aid in debugging and prevent masking underlying issues.

        for attr_name in (
            "__cause__",
            "__context__",
            "cause",
            "reason",
            "original_exception",
        ):
            try:
                nested = getattr(current, attr_name, None)
                if isinstance(nested, BaseException) and id(nested) not in visited:
                    visited.add(id(nested))
                    queue.append(nested)
            except Exception as e:
                logger.warning("Failed to traverse exception attribute %s: %s", attr_name, e)

        for seq_attr in ("args", "errors"):
            try:
                seq = getattr(current, seq_attr, ())
                if isinstance(seq, (tuple, list)):
                    for item in seq:
                        if isinstance(item, BaseException) and id(item) not in visited:
                            visited.add(id(item))
                            queue.append(item)
            except Exception as e:
                logger.warning("Failed to traverse exception sequence attribute %s: %s", seq_attr, e)

References

1. Avoid broad except Exception: blocks that silently return None or pass. Instead, log the exception (e.g., using logger.warning) to aid in debugging and prevent masking underlying issues.