Add new Prometheus metrics to the Cloudflare exporter. Use when adding metrics, implementing new GraphQL/REST queries, or extending metric coverage. Covers the full workflow from schema discovery through client implementation and README updates.
Guided workflow for adding new Prometheus metrics to the Cloudflare Prometheus Exporter. Derived from patterns in PRs #10, #13, #14, #15, and opencode session 1770403408223-happy-garden.
What kind of metric are you adding?
|
+-- Uses Cloudflare GraphQL API?
| |
| +-- Scoped to a single account (no zones)?
| | -> Account-level GraphQL
| | -> See workflow.md, Step A
| |
| +-- Scoped to zones (needs zoneTag_in)?
| -> Zone-level GraphQL
| -> See workflow.md, Step B
|
+-- Uses Cloudflare REST API?
-> REST API (zone-scoped DO)
-> See workflow.md, Step C
| Step | File | Change |
|---|---|---|
| 1 | src/cloudflare/gql/queries.ts | Add graphql() tagged template (skip for REST) |
| 2 |
src/cloudflare/queries.tsAdd to MetricQueryNameSchema enum + category arrays |
| 3 | src/cloudflare/client.ts | Import query, add switch case, implement handler |
| 4 | src/durable-objects/MetricExporter.ts | Only if special guardrails needed (e.g. allowlists) |
| 5 | README.md | Add metric docs + update architecture diagram counts |
cloudflare_<scope>_<thing>_<unit> -- _total for counters, _seconds for durationssnake_case always. Normalize accounts via normalizeAccountName(), zones via findZoneName()noUncheckedIndexedAccess is on -- null-coalesce everything: dims?.field ?? ""return [...metrics].filter(m => m.values.length > 0)const _exhaustive: never = query -- TS errors if case missing| Task | Files |
|---|---|
| Add a metric (full workflow) | workflow.md |
| Copy/paste code templates | patterns.md |
| Avoid known pitfalls | gotchas.md |
| File | Purpose |
|---|---|
| workflow.md | Step-by-step checklist per metric category |
| patterns.md | Code templates for queries, handlers, and MetricDefinitions |
| gotchas.md | Pitfalls from real PRs and code reviews |