feat: Add micro-benchmarks for reads comparing standard (regional) vs rapid (zonal) buckets. (#1697)

* Add performance microbenchmarking suite for Sequential and Random
Reads
* This compares Regional (Standard Storage) with Zonal (Rapid Storage)
buckets.
* Regional uses JSON wheres Zonal uses gRPC bidi
---------
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: chandra-siri

.gitignore

@@ -62,3 +62,6 @@ system_tests/local_test_setup
 # Make sure a generated file isn't accidentally committed.
 pylintrc
 pylintrc.test
+
+# Benchmarking results and logs
+__benchmark_results__/**

setup.py

@@ -60,6 +60,12 @@
 "opentelemetry-api >= 1.1.0, < 2.0.0",
  ],
 "testing": [
+"google-cloud-testutils",
+"numpy",
+"psutil",
+"py-cpuinfo",
+"pytest-benchmark",
+"PyYAML",
 "mock",
 "pytest",
 "pytest-cov",

tests/perf/__init__.py

@@ -0,0 +1,38 @@
+# Performance Microbenchmarks
+
+This directory contains performance microbenchmarks for the Python Storage client library.
+
+## Usage
+
+To run the benchmarks, use `pytest` with the `--benchmark-json` flag to specify an output file for the results.
+
+Example:
+```bash
+pytest --benchmark-json=output.json -vv -s tests/perf/microbenchmarks/reads/test_reads.py
+```
+
+### Running a Specific Test
+
+To run a single test, append `::` followed by the test name to the file path.
+
+Example:
+```bash
+pytest --benchmark-json=output.json -vv -s tests/perf/microbenchmarks/reads/test_reads.py::test_downloads_single_proc_single_coro
+```
+
+## Configuration
+
+The benchmarks are configured using `config.yaml` files located in the respective subdirectories (e.g., `reads/config.yaml`).
+
+## Overriding Buckets
+
+You can override the buckets used in the benchmarks by setting environment variables. Please refer to the specific benchmark implementation for the environment variable names.
+
+## Output
+
+The benchmarks produce a JSON file with the results. This file can be converted to a CSV file for easier analysis in spreadsheets using the provided `json_to_csv.py` script.
+
+Example:
+```bash
+python3 tests/perf/microbenchmarks/json_to_csv.py output.json
+```

tests/perf/microbenchmarks/README.md

@@ -0,0 +1,13 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

tests/perf/microbenchmarks/__init__.py

@@ -0,0 +1,163 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+fromtypingimportAny, List
+importstatistics
+importio
+importos
+
+
+defpublish_benchmark_extra_info(
+benchmark: Any,
+params: Any,
+benchmark_group: str="read",
+true_times: List[float] = [],
+) ->None:
+"""
+ Helper function to publish benchmark parameters to the extra_info property.
+ """
+
+benchmark.extra_info["num_files"] =params.num_files
+benchmark.extra_info["file_size"] =params.file_size_bytes
+benchmark.extra_info["chunk_size"] =params.chunk_size_bytes
+ifbenchmark_group=="write":
+benchmark.extra_info["pattern"] ="seq"
+else:
+benchmark.extra_info["pattern"] =params.pattern
+benchmark.extra_info["coros"] =params.num_coros
+benchmark.extra_info["rounds"] =params.rounds
+benchmark.extra_info["bucket_name"] =params.bucket_name
+benchmark.extra_info["bucket_type"] =params.bucket_type
+benchmark.extra_info["processes"] =params.num_processes
+benchmark.group=benchmark_group
+
+object_size=params.file_size_bytes
+num_files=params.num_files
+total_uploaded_mib= (object_size/ (1024*1024) *num_files)
+min_throughput=total_uploaded_mib/benchmark.stats["max"]
+max_throughput=total_uploaded_mib/benchmark.stats["min"]
+mean_throughput=total_uploaded_mib/benchmark.stats["mean"]
+median_throughput=total_uploaded_mib/benchmark.stats["median"]
+
+benchmark.extra_info["throughput_MiB_s_min"] =min_throughput
+benchmark.extra_info["throughput_MiB_s_max"] =max_throughput
+benchmark.extra_info["throughput_MiB_s_mean"] =mean_throughput
+benchmark.extra_info["throughput_MiB_s_median"] =median_throughput
+
+print("\nThroughput Statistics (MiB/s):")
+print(f" Min: {min_throughput:.2f} (from max time)")
+print(f" Max: {max_throughput:.2f} (from min time)")
+print(f" Mean: {mean_throughput:.2f} (approx, from mean time)")
+print(f" Median: {median_throughput:.2f} (approx, from median time)")
+
+iftrue_times:
+throughputs= [total_uploaded_mib/tfortintrue_times]
+true_min_throughput=min(throughputs)
+true_max_throughput=max(throughputs)
+true_mean_throughput=statistics.mean(throughputs)
+true_median_throughput=statistics.median(throughputs)
+
+benchmark.extra_info["true_throughput_MiB_s_min"] =true_min_throughput
+benchmark.extra_info["true_throughput_MiB_s_max"] =true_max_throughput
+benchmark.extra_info["true_throughput_MiB_s_mean"] =true_mean_throughput
+benchmark.extra_info["true_throughput_MiB_s_median"] =true_median_throughput
+
+print("\nThroughput Statistics from true_times (MiB/s):")
+print(f" Min: {true_min_throughput:.2f}")
+print(f" Max: {true_max_throughput:.2f}")
+print(f" Mean: {true_mean_throughput:.2f}")
+print(f" Median: {true_median_throughput:.2f}")
+
+# Get benchmark name, rounds, and iterations
+name=benchmark.name
+rounds=benchmark.stats['rounds']
+iterations=benchmark.stats['iterations']
+
+# Header for throughput table
+header="\n\n"+"-"*125+"\n"
+header+="Throughput Benchmark (MiB/s)\n"
+header+="-"*125+"\n"
+header+=f"{'Name':<50}{'Min':>10}{'Max':>10}{'Mean':>10}{'StdDev':>10}{'Median':>10}{'Rounds':>8}{'Iterations':>12}\n"
+header+="-"*125
+
+# Data row for throughput table
+# The table headers (Min, Max) refer to the throughput values.
+row=f"{name:<50}{min_throughput:>10.4f}{max_throughput:>10.4f}{mean_throughput:>10.4f}{'N/A':>10}{median_throughput:>10.4f}{rounds:>8}{iterations:>12}"
+
+print(header)
+print(row)
+print("-"*125)
+
+classRandomBytesIO(io.RawIOBase):
+"""
+ A file-like object that generates random bytes using os.urandom.
+ It enforces a fixed size and an upper safety cap.
+ """
+# 10 GiB default safety cap
+DEFAULT_CAP=10*1024*1024*1024
+
+def__init__(self, size, max_size=DEFAULT_CAP):
+"""
+ Args:
+ size (int): The exact size of the virtual file in bytes.
+ max_size (int): The maximum allowed size to prevent safety issues.
+ """
+ifsizeisNone:
+raiseValueError("Size must be defined (cannot be infinite).")
+
+ifsize>max_size:
+raiseValueError(f"Requested size {size} exceeds the maximum limit of {max_size} bytes (10 GiB).")
+
+self._size=size
+self._pos=0
+
+defread(self, n=-1):
+# 1. Handle "read all" (n=-1)
+ifnisNoneorn<0:
+n=self._size-self._pos
+
+# 2. Handle EOF (End of File)
+ifself._pos>=self._size:
+returnb""
+
+# 3. Clamp read amount to remaining size
+# This ensures we stop exactly at `size` bytes.
+n=min(n, self._size-self._pos)
+
+# 4. Generate data
+data=os.urandom(n)
+self._pos+=len(data)
+returndata
+
+defreadable(self):
+returnTrue
+
+defseekable(self):
+returnTrue
+
+deftell(self):
+returnself._pos
+
+defseek(self, offset, whence=io.SEEK_SET):
+ifwhence==io.SEEK_SET:
+new_pos=offset
+elifwhence==io.SEEK_CUR:
+new_pos=self._pos+offset
+elifwhence==io.SEEK_END:
+new_pos=self._size+offset
+else:
+raiseValueError(f"Invalid whence: {whence}")
+
+# Clamp position to valid range [0, size]
+self._pos=max(0, min(new_pos, self._size))
+returnself._pos

tests/perf/microbenchmarks/_utils.py

@@ -0,0 +1,144 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+importcontextlib
+fromtypingimportAny
+fromtests.perf.microbenchmarks.resource_monitorimportResourceMonitor
+importpytest
+fromtests.system._helpersimportdelete_blob
+
+importasyncio
+importmultiprocessing
+importos
+importuuid
+fromgoogle.cloudimportstorage
+fromgoogle.cloud.storage._experimental.asyncio.async_appendable_object_writerimport (
+AsyncAppendableObjectWriter,
+)
+fromgoogle.cloud.storage._experimental.asyncio.async_grpc_clientimportAsyncGrpcClient
+
+_OBJECT_NAME_PREFIX="micro-benchmark"
+
+
+@pytest.fixture(scope="function")
+defblobs_to_delete():
+blobs_to_delete= []
+
+yieldblobs_to_delete
+
+forblobinblobs_to_delete:
+delete_blob(blob)
+
+
+@pytest.fixture(scope="session")
+defstorage_client():
+fromgoogle.cloud.storageimportClient
+
+client=Client()
+withcontextlib.closing(client):
+yieldclient
+
+@pytest.fixture
+defmonitor():
+"""
+ Provides the ResourceMonitor class.
+ Usage: with monitor() as m: ...
+ """
+returnResourceMonitor
+
+defpublish_resource_metrics(benchmark: Any, monitor: ResourceMonitor) ->None:
+"""
+ Helper function to publish resource monitor results to the extra_info property.
+ """
+benchmark.extra_info.update(
+ {
+"cpu_max_global": f"{monitor.max_cpu:.2f}",
+"mem_max": f"{monitor.max_mem:.2f}",
+"net_throughput_mb_s": f"{monitor.throughput_mb_s:.2f}",
+"vcpus": monitor.vcpus,
+ }
+ )
+
+
+asyncdefupload_appendable_object(bucket_name, object_name, object_size, chunk_size):
+# flush interval set to little over 1GiB to minimize number of flushes.
+# this method is to write "appendable" objects which will be used for 
+# benchmarking reads, hence not concerned performance of writes here.
+writer=AsyncAppendableObjectWriter(
+AsyncGrpcClient().grpc_client, bucket_name, object_name, writer_options={"FLUSH_INTERVAL_BYTES": 1026*1024**2}
+ )
+awaitwriter.open()
+uploaded_bytes=0
+whileuploaded_bytes<object_size:
+bytes_to_upload=min(chunk_size, object_size-uploaded_bytes)
+awaitwriter.append(os.urandom(bytes_to_upload))
+uploaded_bytes+=bytes_to_upload
+object_metdata=awaitwriter.close(finalize_on_close=True)
+assertobject_metdata.size==uploaded_bytes
+returnuploaded_bytes
+
+
+defupload_simple_object(bucket_name, object_name, object_size, chunk_size):
+storage_client=storage.Client()
+bucket=storage_client.bucket(bucket_name)
+blob=bucket.blob(object_name)
+blob.chunk_size=chunk_size
+data=os.urandom(object_size)
+blob.upload_from_string(data)
+returnobject_size
+
+
+def_upload_worker(args):
+bucket_name, object_name, object_size, chunk_size, bucket_type=args
+ifbucket_type=="zonal":
+uploaded_bytes=asyncio.run(
+upload_appendable_object(bucket_name, object_name, object_size, chunk_size)
+ )
+else:
+uploaded_bytes=upload_simple_object(bucket_name, object_name, object_size, chunk_size)
+returnobject_name, uploaded_bytes
+
+
+def_create_files(num_files, bucket_name, bucket_type, object_size, chunk_size=1024*1024*1024):
+"""
+ Create/Upload objects for benchmarking and return a list of their names.
+ """
+object_names= [
+f"{_OBJECT_NAME_PREFIX}-{uuid.uuid4().hex[:5]}"for_inrange(num_files)
+ ]
+
+args_list= [
+ (bucket_name, object_names[i], object_size, chunk_size, bucket_type)
+foriinrange(num_files)
+ ]
+
+ctx=multiprocessing.get_context("spawn")
+withctx.Pool() aspool:
+results=pool.map(_upload_worker, args_list)
+
+total_uploaded_bytes=sum(r[1] forrinresults)
+asserttotal_uploaded_bytes==object_size*num_files
+
+return [r[0] forrinresults]
+
+
+@pytest.fixture
+defworkload_params(request):
+params=request.param
+files_names=_create_files(
+params.num_files,
+params.bucket_name,
+params.bucket_type,
+params.file_size_bytes,
+ )
+returnparams, files_names