stac-api-load-testing 0.3.1__tar.gz → 0.4.0__tar.gz

{stac_api_load_testing-0.3.1/stac_api_load_testing.egg-info → stac_api_load_testing-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stac-api-load-testing
-Version: 0.3.1
+Version: 0.4.0
 Summary: Load testing for stac compliant apis
 Author-email: Jonathan Healy <jonathan.d.healy@gmail.com>
 License: MIT
@@ -68,6 +68,11 @@ Usage: stac-api-load-testing [OPTIONS]
 
 Options:
   -i, --ingest               Ingest sample data into the STAC API.
+  --collections INTEGER      Number of collections to create for --ingest.
+  --items-per-collection INTEGER
+                             Items per collection for --ingest; beyond the
+                             100 bundled items, duplicates are synthesized
+                             with new ids and shifted geometry.
   -l, --locust               Run Locust load tests against the STAC API.
   -t, --taurus               Run the Taurus wrapper for performance testing
                              against the STAC API.
@@ -83,6 +88,8 @@ Options:
   --spawn-rate INTEGER       Users spawned per second for --benchmark.
   --run-time TEXT            Duration of each --benchmark run, in locust
                              notation (e.g. '30s', '1m').
+  -w, --workers INTEGER      Locust worker processes for --benchmark; >1
+                             distributes load across cores on this machine.
   -o, --output PATH          Write aggregated --benchmark results to a CSV
                              file.
   --version                  Show the version and exit.
@@ -92,6 +99,10 @@ Options:
 ## Ingest test data - http://localhost:8084 is just an example url
 ```$ stac-api-load-testing --ingest --api-address http://localhost:8084```
 
+Larger synthetic datasets: `--collections` creates `test-collection`, `test-collection-2`, ..., and `--items-per-collection` controls items per collection. Above the 100 bundled items, duplicates are derived from the sample features with new ids and randomly relocated geometry:
+
+```$ stac-api-load-testing --ingest --api-address http://localhost:8084 --collections 2 --items-per-collection 500```
+
 ## Run Locust Load Testing Ouside of Taurus Wrapper
 ```$ stac-api-load-testing --locust --api-address http://localhost:8084```  
 - go to ```http://localhost:8089``` and start with desired settings
@@ -110,39 +121,48 @@ Compare multiple backends in one command (comma-separated addresses):
 
 ```$ stac-api-load-testing --benchmark --api-address http://localhost:8085,http://localhost:8087 --users 10,50,100 --run-time 1m -o results.csv```
 
-## Example benchmark: stac-fastapi-os vs stac-os-rs
+## Example benchmark: pgstac vs opensearch vs stac-os-rs
 
 Methodology used for the comparison below:
 
-1. Start each backend with its own dedicated OpenSearch 3.8.0 instance (2GB heap each):
+1. Start all three backends, each with its own datastore on a ~2GB memory budget (OpenSearch 3.8.0 `-Xms2g -Xmx2g`, pgstac `shared_buffers=2GB`):
+
+   ```$ docker compose up -d opensearch opensearch-rs app-opensearch app-stac-os-rs pgstac app-pgstac```
 
-   ```$ docker compose up -d opensearch opensearch-rs app-opensearch app-stac-os-rs```
+2. Ingest the same dataset into each backend — 4 collections with 500 Sentinel-2 L2A items each (2,000 items total):
 
-2. Ingest the same dataset into both backends — 1 collection (`test-collection`) with 100 Sentinel-2 L2A items:
+   ```$ stac-api-load-testing --ingest --api-address http://localhost:8083 --collections 4 --items-per-collection 500```   
+   ```$ stac-api-load-testing --ingest --api-address http://localhost:8085 --collections 4 --items-per-collection 500```   
+   ```$ stac-api-load-testing --ingest --api-address http://localhost:8087 --collections 4 --items-per-collection 500```
 
-   ```$ stac-api-load-testing --ingest --api-address http://localhost:8085```   
-   ```$ stac-api-load-testing --ingest --api-address http://localhost:8087```
+3. Run the benchmark sweep against all three in one command (10/50/100/150 users, spawn rate 10 users/s, 1 minute per run, 8 locust worker processes):
 
-3. Run the benchmark sweep against both in one command (10/50/100 users, spawn rate 10 users/s, 1 minute per run):
+   ```$ stac-api-load-testing --benchmark --api-address stac-fastapi-pgstac=http://localhost:8083,stac-fastapi-os=http://localhost:8085,stac-os-rs=http://localhost:8087 --users 10,50,100,150 --run-time 1m -w 8 -o results.csv```
 
-   ```$ stac-api-load-testing --benchmark --api-address http://localhost:8085,http://localhost:8087 --users 10,50,100 --run-time 1m -o results.csv```
+Environment: AMD Ryzen 7 8845HS (16 threads), 28GB RAM, Docker 29.8.0, locust 2.47.0 (`-w 8`), stac-fastapi.pgstac 7.2.0, stac-fastapi-os v8.1.1, stac-os-rs 0.5.0. The locustfile drives a read/search workload — landing page, collections, collection items, single items across all collections, GET/POST `/search` with bbox, intersects, sortby, datetime, CQL2, and ids queries, one level of `next`-link pagination, and filtered item lists; every search uses `limit=10`; write tasks are disabled.
 
-Environment: AMD Ryzen 7 8845HS (16 threads), 28GB RAM, Docker 29.8.0, locust 2.47.0, stac-fastapi-os v8.1.1, stac-os-rs 0.2.0. The locustfile drives a read/search workload — landing page, collections, collection items, single items, and GET/POST `/search` with bbox, intersects, and sortby queries; write tasks are disabled.
+Note on parity: stac-fastapi-os and stac-os-rs compute `numberMatched` (total-hit counting) on every search, while this stac-fastapi-pgstac version ships no context extension and skips count work entirely — so pgstac's reported numbers do not include a cost the OpenSearch-backed APIs pay per query.
 
 ### Results
 
-| api | users | requests | failures | median (ms) | p95 (ms) | p99 (ms) | req/s |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| stac-fastapi-os (:8085) | 10 | 48,672 | 0 | 9 | 24 | 32 | 822 |
-| stac-fastapi-os (:8085) | 50 | 51,659 | 0 | 48 | 88 | 110 | 864 |
-| stac-fastapi-os (:8085) | 100 | 47,758 | 0 | 100 | 170 | 210 | 800 |
-| stac-os-rs (:8087) | 10 | 75,601 | 0 | 6 | 19 | 36 | 1,276 |
-| stac-os-rs (:8087) | 50 | 75,769 | 0 | 33 | 62 | 190 | 1,264 |
-| stac-os-rs (:8087) | 100 | 72,621 | 0 | 64 | 120 | 360 | 1,220 |
+| api | collections | items | users | requests | failures | median (ms) | p95 (ms) | p99 (ms) | req/s |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| stac-fastapi-pgstac (:8083) | 4 | 2,000 | 10 | 11,252 | 0 | 27 | 140 | 170 | 187 |
+| stac-fastapi-pgstac (:8083) | 4 | 2,000 | 50 | 13,817 | 0 | 54 | 780 | 2,500 | 230 |
+| stac-fastapi-pgstac (:8083) | 4 | 2,000 | 100 | 13,629 | 0 | 120 | 1,300 | 5,900 | 227 |
+| stac-fastapi-pgstac (:8083) | 4 | 2,000 | 150 | 13,619 | 0 | 250 | 1,600 | 7,300 | 227 |
+| stac-fastapi-os (:8085) | 4 | 2,000 | 10 | 49,492 | 0 | 9 | 25 | 32 | 824 |
+| stac-fastapi-os (:8085) | 4 | 2,000 | 50 | 59,998 | 0 | 43 | 98 | 140 | 999 |
+| stac-fastapi-os (:8085) | 4 | 2,000 | 100 | 58,755 | 0 | 90 | 170 | 220 | 978 |
+| stac-fastapi-os (:8085) | 4 | 2,000 | 150 | 51,455 | 0 | 150 | 270 | 330 | 857 |
+| stac-os-rs (:8087) | 4 | 2,000 | 10 | 100,517 | 0 | 5 | 10 | 12 | 1,674 |
+| stac-os-rs (:8087) | 4 | 2,000 | 50 | 131,865 | 0 | 20 | 38 | 47 | 2,196 |
+| stac-os-rs (:8087) | 4 | 2,000 | 100 | 130,389 | 0 | 40 | 68 | 82 | 2,170 |
+| stac-os-rs (:8087) | 4 | 2,000 | 150 | 105,080 | 0 | 72 | 120 | 150 | 1,748 |
 
 ### Summary
 
-stac-os-rs sustained ~45-55% higher throughput than stac-fastapi-os at every concurrency level (peaks of ~1,270 vs ~860 req/s) with lower median latency, and zero failures on either backend. stac-fastapi-os saturates near 50 users — median latency climbs 9→48→100ms while throughput stays flat — whereas stac-os-rs plateaus at a higher request rate. Caveat: locust reported >90% CPU on the load generator during all stac-os-rs runs, so its true ceiling is likely higher than measured; distributed locust workers would give a more precise figure. These numbers reflect a small (100-item) dataset on a single machine and should be treated as relative comparison, not absolute capacity.
+stac-os-rs sustained ~2.2x the throughput of stac-fastapi-os and ~8.8x stac-fastapi-pgstac, peaking at ~2,200 req/s with zero failures across all twelve runs. All three backends saturate by ~100 users on this box — throughput knees at ~250 (pgstac), ~1,000 (fastapi-os), and ~2,200 (stac-os-rs) req/s; at 150 users each shows the classic overload curve with declining throughput and rising latency. The OpenSearch-backed APIs degrade without errors, as does pgstac — its earlier failures (CQL2 500s, dropped connections) traced to Docker's 64MB `/dev/shm` default starving Postgres parallel-query workers, fixed by `shm_size: 1gb` on the pgstac container; with that resolved its ~230 req/s ceiling is clean but its p99 still reaches 7.3s at 150 users. Running enough locust workers matters: in single-process runs the same setup measured only ~1,000 req/s because the load generator itself was CPU-bound — with `-w 8` no CPU warnings appeared and reported numbers reflect the backends. These numbers reflect a 2,000-item dataset on a single machine and should be treated as a relative comparison, not absolute capacity.
 
 ## Debugging Locust tasks using a single simulated user
 ```$ python stac_api_load_testing/config_files/locustfile.py```

{stac_api_load_testing-0.3.1 → stac_api_load_testing-0.4.0}/README.md

@@ -49,6 +49,11 @@ Usage: stac-api-load-testing [OPTIONS]
 
 Options:
   -i, --ingest               Ingest sample data into the STAC API.
+  --collections INTEGER      Number of collections to create for --ingest.
+  --items-per-collection INTEGER
+                             Items per collection for --ingest; beyond the
+                             100 bundled items, duplicates are synthesized
+                             with new ids and shifted geometry.
   -l, --locust               Run Locust load tests against the STAC API.
   -t, --taurus               Run the Taurus wrapper for performance testing
                              against the STAC API.
@@ -64,6 +69,8 @@ Options:
   --spawn-rate INTEGER       Users spawned per second for --benchmark.
   --run-time TEXT            Duration of each --benchmark run, in locust
                              notation (e.g. '30s', '1m').
+  -w, --workers INTEGER      Locust worker processes for --benchmark; >1
+                             distributes load across cores on this machine.
   -o, --output PATH          Write aggregated --benchmark results to a CSV
                              file.
   --version                  Show the version and exit.
@@ -73,6 +80,10 @@ Options:
 ## Ingest test data - http://localhost:8084 is just an example url
 ```$ stac-api-load-testing --ingest --api-address http://localhost:8084```
 
+Larger synthetic datasets: `--collections` creates `test-collection`, `test-collection-2`, ..., and `--items-per-collection` controls items per collection. Above the 100 bundled items, duplicates are derived from the sample features with new ids and randomly relocated geometry:
+
+```$ stac-api-load-testing --ingest --api-address http://localhost:8084 --collections 2 --items-per-collection 500```
+
 ## Run Locust Load Testing Ouside of Taurus Wrapper
 ```$ stac-api-load-testing --locust --api-address http://localhost:8084```  
 - go to ```http://localhost:8089``` and start with desired settings
@@ -91,39 +102,48 @@ Compare multiple backends in one command (comma-separated addresses):
 
 ```$ stac-api-load-testing --benchmark --api-address http://localhost:8085,http://localhost:8087 --users 10,50,100 --run-time 1m -o results.csv```
 
-## Example benchmark: stac-fastapi-os vs stac-os-rs
+## Example benchmark: pgstac vs opensearch vs stac-os-rs
 
 Methodology used for the comparison below:
 
-1. Start each backend with its own dedicated OpenSearch 3.8.0 instance (2GB heap each):
+1. Start all three backends, each with its own datastore on a ~2GB memory budget (OpenSearch 3.8.0 `-Xms2g -Xmx2g`, pgstac `shared_buffers=2GB`):
+
+   ```$ docker compose up -d opensearch opensearch-rs app-opensearch app-stac-os-rs pgstac app-pgstac```
 
-   ```$ docker compose up -d opensearch opensearch-rs app-opensearch app-stac-os-rs```
+2. Ingest the same dataset into each backend — 4 collections with 500 Sentinel-2 L2A items each (2,000 items total):
 
-2. Ingest the same dataset into both backends — 1 collection (`test-collection`) with 100 Sentinel-2 L2A items:
+   ```$ stac-api-load-testing --ingest --api-address http://localhost:8083 --collections 4 --items-per-collection 500```   
+   ```$ stac-api-load-testing --ingest --api-address http://localhost:8085 --collections 4 --items-per-collection 500```   
+   ```$ stac-api-load-testing --ingest --api-address http://localhost:8087 --collections 4 --items-per-collection 500```
 
-   ```$ stac-api-load-testing --ingest --api-address http://localhost:8085```   
-   ```$ stac-api-load-testing --ingest --api-address http://localhost:8087```
+3. Run the benchmark sweep against all three in one command (10/50/100/150 users, spawn rate 10 users/s, 1 minute per run, 8 locust worker processes):
 
-3. Run the benchmark sweep against both in one command (10/50/100 users, spawn rate 10 users/s, 1 minute per run):
+   ```$ stac-api-load-testing --benchmark --api-address stac-fastapi-pgstac=http://localhost:8083,stac-fastapi-os=http://localhost:8085,stac-os-rs=http://localhost:8087 --users 10,50,100,150 --run-time 1m -w 8 -o results.csv```
 
-   ```$ stac-api-load-testing --benchmark --api-address http://localhost:8085,http://localhost:8087 --users 10,50,100 --run-time 1m -o results.csv```
+Environment: AMD Ryzen 7 8845HS (16 threads), 28GB RAM, Docker 29.8.0, locust 2.47.0 (`-w 8`), stac-fastapi.pgstac 7.2.0, stac-fastapi-os v8.1.1, stac-os-rs 0.5.0. The locustfile drives a read/search workload — landing page, collections, collection items, single items across all collections, GET/POST `/search` with bbox, intersects, sortby, datetime, CQL2, and ids queries, one level of `next`-link pagination, and filtered item lists; every search uses `limit=10`; write tasks are disabled.
 
-Environment: AMD Ryzen 7 8845HS (16 threads), 28GB RAM, Docker 29.8.0, locust 2.47.0, stac-fastapi-os v8.1.1, stac-os-rs 0.2.0. The locustfile drives a read/search workload — landing page, collections, collection items, single items, and GET/POST `/search` with bbox, intersects, and sortby queries; write tasks are disabled.
+Note on parity: stac-fastapi-os and stac-os-rs compute `numberMatched` (total-hit counting) on every search, while this stac-fastapi-pgstac version ships no context extension and skips count work entirely — so pgstac's reported numbers do not include a cost the OpenSearch-backed APIs pay per query.
 
 ### Results
 
-| api | users | requests | failures | median (ms) | p95 (ms) | p99 (ms) | req/s |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| stac-fastapi-os (:8085) | 10 | 48,672 | 0 | 9 | 24 | 32 | 822 |
-| stac-fastapi-os (:8085) | 50 | 51,659 | 0 | 48 | 88 | 110 | 864 |
-| stac-fastapi-os (:8085) | 100 | 47,758 | 0 | 100 | 170 | 210 | 800 |
-| stac-os-rs (:8087) | 10 | 75,601 | 0 | 6 | 19 | 36 | 1,276 |
-| stac-os-rs (:8087) | 50 | 75,769 | 0 | 33 | 62 | 190 | 1,264 |
-| stac-os-rs (:8087) | 100 | 72,621 | 0 | 64 | 120 | 360 | 1,220 |
+| api | collections | items | users | requests | failures | median (ms) | p95 (ms) | p99 (ms) | req/s |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| stac-fastapi-pgstac (:8083) | 4 | 2,000 | 10 | 11,252 | 0 | 27 | 140 | 170 | 187 |
+| stac-fastapi-pgstac (:8083) | 4 | 2,000 | 50 | 13,817 | 0 | 54 | 780 | 2,500 | 230 |
+| stac-fastapi-pgstac (:8083) | 4 | 2,000 | 100 | 13,629 | 0 | 120 | 1,300 | 5,900 | 227 |
+| stac-fastapi-pgstac (:8083) | 4 | 2,000 | 150 | 13,619 | 0 | 250 | 1,600 | 7,300 | 227 |
+| stac-fastapi-os (:8085) | 4 | 2,000 | 10 | 49,492 | 0 | 9 | 25 | 32 | 824 |
+| stac-fastapi-os (:8085) | 4 | 2,000 | 50 | 59,998 | 0 | 43 | 98 | 140 | 999 |
+| stac-fastapi-os (:8085) | 4 | 2,000 | 100 | 58,755 | 0 | 90 | 170 | 220 | 978 |
+| stac-fastapi-os (:8085) | 4 | 2,000 | 150 | 51,455 | 0 | 150 | 270 | 330 | 857 |
+| stac-os-rs (:8087) | 4 | 2,000 | 10 | 100,517 | 0 | 5 | 10 | 12 | 1,674 |
+| stac-os-rs (:8087) | 4 | 2,000 | 50 | 131,865 | 0 | 20 | 38 | 47 | 2,196 |
+| stac-os-rs (:8087) | 4 | 2,000 | 100 | 130,389 | 0 | 40 | 68 | 82 | 2,170 |
+| stac-os-rs (:8087) | 4 | 2,000 | 150 | 105,080 | 0 | 72 | 120 | 150 | 1,748 |
 
 ### Summary
 
-stac-os-rs sustained ~45-55% higher throughput than stac-fastapi-os at every concurrency level (peaks of ~1,270 vs ~860 req/s) with lower median latency, and zero failures on either backend. stac-fastapi-os saturates near 50 users — median latency climbs 9→48→100ms while throughput stays flat — whereas stac-os-rs plateaus at a higher request rate. Caveat: locust reported >90% CPU on the load generator during all stac-os-rs runs, so its true ceiling is likely higher than measured; distributed locust workers would give a more precise figure. These numbers reflect a small (100-item) dataset on a single machine and should be treated as relative comparison, not absolute capacity.
+stac-os-rs sustained ~2.2x the throughput of stac-fastapi-os and ~8.8x stac-fastapi-pgstac, peaking at ~2,200 req/s with zero failures across all twelve runs. All three backends saturate by ~100 users on this box — throughput knees at ~250 (pgstac), ~1,000 (fastapi-os), and ~2,200 (stac-os-rs) req/s; at 150 users each shows the classic overload curve with declining throughput and rising latency. The OpenSearch-backed APIs degrade without errors, as does pgstac — its earlier failures (CQL2 500s, dropped connections) traced to Docker's 64MB `/dev/shm` default starving Postgres parallel-query workers, fixed by `shm_size: 1gb` on the pgstac container; with that resolved its ~230 req/s ceiling is clean but its p99 still reaches 7.3s at 150 users. Running enough locust workers matters: in single-process runs the same setup measured only ~1,000 req/s because the load generator itself was CPU-bound — with `-w 8` no CPU warnings appeared and reported numbers reflect the backends. These numbers reflect a 2,000-item dataset on a single machine and should be treated as a relative comparison, not absolute capacity.
 
 ## Debugging Locust tasks using a single simulated user
 ```$ python stac_api_load_testing/config_files/locustfile.py```

{stac_api_load_testing-0.3.1 → stac_api_load_testing-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stac-api-load-testing"
-version = "0.3.1"
+version = "0.4.0"
 description = "Load testing for stac compliant apis"
 readme = "README.md"
 requires-python = ">=3.11"

{stac_api_load_testing-0.3.1 → stac_api_load_testing-0.4.0}/stac_api_load_testing/cli.py

@@ -1,6 +1,7 @@
 """stac-api-load-testing cli tool."""
 
 import csv
+import json
 import os
 import re
 import shutil
@@ -11,6 +12,7 @@ from importlib import resources
 from pathlib import Path
 
 import click
+import requests
 import yaml
 
 from .data_loader import data_loader
@@ -74,12 +76,81 @@ def _read_aggregated_stats(csv_path: str) -> dict:
     return {}
 
 
+def _collection_ids(base_url: str) -> list:
+    """Return all collection ids served by a STAC API."""
+    response = requests.get(f"{base_url}/collections", timeout=30)
+    response.raise_for_status()
+    return [c["id"] for c in response.json().get("collections", [])]
+
+
+def _collection_item_count(base_url: str, collection_id: str) -> int:
+    """Count items in one collection, preferring the cheap numberMatched field."""
+    response = requests.post(
+        f"{base_url}/search",
+        json={"collections": [collection_id], "limit": 1},
+        timeout=30,
+    )
+    response.raise_for_status()
+    matched = response.json().get("numberMatched")
+    if matched is not None:
+        return matched
+
+    # APIs without the context extension: count by paging the items endpoint.
+    count = 0
+    url = f"{base_url}/collections/{collection_id}/items?limit=500"
+    for _ in range(100):
+        response = requests.get(url, timeout=60)
+        response.raise_for_status()
+        page = response.json()
+        count += len(page.get("features", []))
+        url = next(
+            (
+                link["href"]
+                for link in page.get("links", [])
+                if link.get("rel") == "next" and link.get("href")
+            ),
+            None,
+        )
+        if url is None:
+            return count
+    return count
+
+
+def _api_metadata(base_url: str) -> dict:
+    """Fetch the catalog title and dataset size from a STAC API.
+
+    Returns a dict with 'name', 'collections' and 'items' keys; fields are
+    empty when the API is unreachable or doesn't report them.
+    """
+    meta: dict[str, object] = {"name": "", "collections": "", "items": ""}
+    try:
+        response = requests.get(base_url, timeout=30)
+        response.raise_for_status()
+        meta["name"] = response.json().get("title", "")
+    except requests.RequestException as exc:
+        click.secho(f"could not fetch catalog info from {base_url}: {exc}", fg="yellow")
+
+    try:
+        collection_ids = _collection_ids(base_url)
+        meta["collections"] = len(collection_ids)
+        counts = {
+            collection_id: _collection_item_count(base_url, collection_id)
+            for collection_id in collection_ids
+        }
+        meta["items"] = sum(counts.values())
+        meta["collection_counts"] = counts
+    except requests.RequestException as exc:
+        click.secho(f"could not count items in {base_url}: {exc}", fg="yellow")
+    return meta
+
+
 def run_benchmark(
     api_addresses: list,
     concurrency_levels: list,
     spawn_rate: int,
     run_time: str,
     output: str,
+    workers: int,
 ):
     """
     Run headless Locust benchmark sweeps against one or more STAC APIs.
@@ -94,37 +165,56 @@ def run_benchmark(
         spawn_rate (int): Users spawned per second in each run.
         run_time (str): Duration of each run, in locust notation (e.g. '30s').
         output (str): Optional path to write aggregated results as CSV.
+        workers (int): Locust worker processes (--processes); >1 runs
+            distributed on this machine to avoid a single-process CPU ceiling.
     """
     locustfile_path = _package_resource("config_files", "locustfile.py")
     results = []
 
-    for address in api_addresses:
+    for target in api_addresses:
+        # Targets can be labelled: "name=http://..." overrides the catalog title.
+        name, _, address = target.partition("=")
+        if not address:
+            name, address = "", target
+
+        meta = _api_metadata(address)
+        api_name = name or meta["name"] or address
+        # Locust workers derive item ids locally and need only the count.
+        os.environ["STAC_COLLECTION_COUNTS"] = json.dumps(
+            meta.get("collection_counts") or {}
+        )
+        click.secho(
+            f"\n=== {api_name} ({address}) — "
+            f"{meta['collections']} collections, {meta['items']} items ===",
+            fg="cyan",
+        )
         for users in concurrency_levels:
             click.secho(f"\n>>> {address} @ {users} users for {run_time}", fg="cyan")
             with tempfile.TemporaryDirectory() as tmpdir:
                 csv_prefix = os.path.join(tmpdir, "locust")
                 stats_csv = f"{csv_prefix}_stats.csv"
+                cmd = [
+                    _tool_path("locust"),
+                    "--locustfile",
+                    locustfile_path,
+                    "--host",
+                    address,
+                    "--headless",
+                    "-u",
+                    str(users),
+                    "-r",
+                    str(spawn_rate),
+                    "-t",
+                    run_time,
+                    "--csv",
+                    csv_prefix,
+                    "--only-summary",
+                ]
+                if workers > 1:
+                    cmd += ["--processes", str(workers)]
                 # locust exits non-zero when requests fail; under load that is
                 # data (backend errors), not a benchmark tool error.
-                subprocess.run(
-                    [
-                        _tool_path("locust"),
-                        "--locustfile",
-                        locustfile_path,
-                        "--host",
-                        address,
-                        "--headless",
-                        "-u",
-                        str(users),
-                        "-r",
-                        str(spawn_rate),
-                        "-t",
-                        run_time,
-                        "--csv",
-                        csv_prefix,
-                        "--only-summary",
-                    ]
-                )
+                subprocess.run(cmd)
 
                 if not os.path.exists(stats_csv):
                     click.secho(
@@ -137,7 +227,10 @@ def run_benchmark(
                 if stats:
                     results.append(
                         {
-                            "api": address,
+                            "api": api_name,
+                            "url": address,
+                            "collections": meta["collections"],
+                            "items": meta["items"],
                             "users": users,
                             "requests": stats.get("Request Count"),
                             "failures": stats.get("Failure Count"),
@@ -152,12 +245,16 @@ def run_benchmark(
         click.secho("No benchmark results collected.", fg="red")
         return
 
-    header = f"{'api':<26}{'users':>7}{'reqs':>9}{'fails':>7}{'med':>8}{'p95':>8}{'p99':>8}{'rps':>9}"
+    header = (
+        f"{'api':<36}{'colls':>6}{'items':>7}{'users':>7}{'reqs':>9}"
+        f"{'fails':>7}{'med':>8}{'p95':>8}{'p99':>8}{'rps':>9}"
+    )
     click.echo("\n" + header)
     click.echo("-" * len(header))
     for row in results:
         click.echo(
-            f"{row['api']:<26}{row['users']:>7}{row['requests']:>9}"
+            f"{row['api']:<36}{row['collections']:>6}{row['items']:>7}"
+            f"{row['users']:>7}{row['requests']:>9}"
             f"{row['failures']:>7}{row['median_ms']:>8}{row['p95_ms']:>8}"
             f"{row['p99_ms']:>8}{row['rps']:>9}"
         )
@@ -202,7 +299,19 @@ def run_benchmark(
     "-a",
     "--api-address",
     default="http://localhost:8080",
-    help="Specify the STAC API URL to test against. Accepts a comma-separated list for --benchmark.",
+    help="Specify the STAC API URL to test against. Accepts a comma-separated list for --benchmark; prefix with 'name=' to label a target in results.",
+)
+@click.option(
+    "--collections",
+    default=1,
+    help="Number of collections to create for --ingest (test-collection, test-collection-2, ...).",
+    type=int,
+)
+@click.option(
+    "--items-per-collection",
+    default=100,
+    help="Items to load per collection for --ingest; beyond the 100 bundled items, duplicates are synthesized with new ids and shifted geometry.",
+    type=int,
 )
 @click.option(
     "-b",
@@ -227,6 +336,13 @@ def run_benchmark(
     default="30s",
     help="Duration of each --benchmark run, in locust notation (e.g. '30s', '1m').",
 )
+@click.option(
+    "-w",
+    "--workers",
+    default=1,
+    help="Locust worker processes for --benchmark (--processes); >1 distributes load across cores on this machine.",
+    type=int,
+)
 @click.option(
     "-o",
     "--output",
@@ -234,7 +350,7 @@ def run_benchmark(
     help="Write aggregated --benchmark results to a CSV file.",
     type=click.Path(),
 )
-@click.version_option(version="0.3.1")
+@click.version_option(version="0.4.0")
 def main(
     ingest: bool,
     locust: bool,
@@ -243,10 +359,13 @@ def main(
     concurrency: int,
     ramp_up: str,
     iterations: int,
+    collections: int,
+    items_per_collection: int,
     benchmark: bool,
     users: str,
     spawn_rate: int,
     run_time: str,
+    workers: int,
     output: str,
 ):
     """
@@ -262,18 +381,26 @@ def main(
         concurrency (int): Specifies the number of concurrent users for Taurus testing. Default is 10.
         ramp_up (str): Specifies the ramp-up period for Taurus testing, in Taurus notation (e.g., '1m' for 1 minute). Default is '1m'.
         iterations (int): Specifies the number of iterations each virtual user will execute in Taurus testing. Default is 100.
+        collections (int): Number of collections to create for ingest. Default 1.
+        items_per_collection (int): Items per collection for ingest. Default 100;
+            above 100, duplicates are synthesized with new ids and shifted geometry.
         api_address (str): The base URL of the STAC API to be tested. Comma-separated list allowed for benchmark.
         benchmark (bool): If True, run headless locust runs sweeping --users levels and print a comparison table.
         users (str): Comma-separated concurrency levels for benchmark. Default '10,50,100'.
         spawn_rate (int): Users spawned per second in each benchmark run. Default 10.
         run_time (str): Duration of each benchmark run in locust notation. Default '30s'.
+        workers (int): Locust worker processes per benchmark run. Default 1.
         output (str): Optional CSV file path for aggregated benchmark results.
     """
     os.environ["LOCUST_HOST"] = api_address
 
     if ingest:
         # Load data into the STAC API
-        data_loader.load_items(stac_api_base_url=api_address)
+        data_loader.load_items(
+            stac_api_base_url=api_address,
+            num_collections=collections,
+            items_per_collection=items_per_collection,
+        )
     elif locust:
         # Execute Locust load tests
         locust_file_path = _package_resource("config_files", "locustfile.py")
@@ -301,7 +428,9 @@ def main(
     elif benchmark:
         concurrency_levels = [int(x) for x in users.split(",")]
         api_addresses = [a.strip() for a in api_address.split(",")]
-        run_benchmark(api_addresses, concurrency_levels, spawn_rate, run_time, output)
+        run_benchmark(
+            api_addresses, concurrency_levels, spawn_rate, run_time, output, workers
+        )
 
 
 if __name__ == "__main__":