Why it exists¶
A single cloudg map -p aws --org --regions all runs 133 deep collectors, a Cloud Control sweep and a tagging sweep in every region of every member account, and several collectors fan out per item (one DescribeImageAttribute call per AMI, for example). Azure is read per subscription through Resource Manager and Resource Graph, GCP per project or organization through Cloud Asset Inventory. Every one of those APIs has a request quota, and most of them are shared with whatever else runs in the account: CI pipelines, Terraform, the console, other auditors.
Up to 0.5.x, cloudg relied on each SDK's own retries. That works for one region of one account. At organization scale it had three problems. Clients did not know about each other, so forty concurrent EC2 clients in one account each backed off on their own and kept the account's bucket empty. A service that stayed throttled made its collector fail outright, which looked the same in coverage as an access error. And nothing remembered that an API had just pushed back.
The third problem got worse with the MCP layer. An AI agent can call map_inventory again a minute after the last run finished, and again after that, which a person running cloudg map would not do. Each repeat starts every collector from full speed against APIs that are still recovering.
The package addresses those with one shared, process-wide governor:
- calls are paced by token buckets shared by every client in the process, set at or below each provider's published limits;
- a throttled scope slows down for everyone using it and speeds up again gradually;
- a service that stays throttled is cut off by a circuit breaker for a while, and the rest of the map continues;
- the outcome is recorded: coverage says
throttled: ..., and the map carries athrottlingblock with per-scope counters; - live collections triggered through MCP are deduplicated, capped and cooled down.