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](./references/workflow.md) | Step-by-step checklist per metric category | | [patterns.md](./references/patterns.md) | Code templates for queries, handlers, and MetricDefinitions | | [gotchas.md](./references/gotchas.md) | Pitfalls from real PRs and code reviews |