adding-metrics

name	adding-metrics
description	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.

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