Adding Metrics

Adding Metrics

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.

Decision Tree

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

Quick Reference: Files to Modify

| Step | File | Change |

|------|------|--------|

| 1 | src/cloudflare/gql/queries.ts | Add graphql() tagged template (skip for REST) |

| 2 | src/cloudflare/queries.ts | Add 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 |

Key Conventions

• Metric names: cloudflare_<scope>_<thing>_<unit> -- _total for counters, _seconds for durations
• Label keys: snake_case always. Normalize accounts via normalizeAccountName(), zones via findZoneName()
• Counter vs Gauge: counters for window totals (DO accumulates); gauges for snapshots/rates/ratios
• Null safety: noUncheckedIndexedAccess is on -- null-coalesce everything: dims?.field ?? ""
• Empty filter: Always return [...metrics].filter(m => m.values.length > 0)
• Exhaustive switch: Both dispatch methods use const _exhaustive: never = query -- TS errors if case missing

Reading Order

| Task | Files |

|------|-------|

| Add a metric (full workflow) | workflow.md |

| Copy/paste code templates | patterns.md |

| Avoid known pitfalls | gotchas.md |

In This Reference

| 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 |