feat(cli): add metrics resources command for CPU, memory and GPU memory

[jonoirwinrsa]

Stacked on #92 — base is feat/cli-json-output. Review that one first; merging it will retarget this to main.

Why

An agent that has just run cerebrium deploy can now see whether its app is up (#92), but not whether the hardware in cerebrium.toml is the right size.

cerebrium metrics resources APP reports the three numbers that answer it — CPU, memory, and GPU memory (VRAM) — from the resource-metrics endpoint.

$ cerebrium metrics resources brainiac-h3-v4 --start 2026-08-06T17:30:00Z --end 2026-08-06T19:00:00Z
Peak usage for p-367e7969-brainiac-h3-v4 (app) from 2026-08-06T17:30:00Z to 2026-08-06T19:00:00Z

METRIC               Max       P50       P90  UNIT
CPU                 1.04      1.04      1.04  cores
Memory            185.17    185.17    185.17  GB
GPU Memory             -         -         -  GB

Defaults to the last hour. --since, --start/--end, --container-id and --resolution narrow it; --output json returns the summary plus the raw series so an agent can do its own analysis.

Deliberately narrow: the backend also exposes latency percentiles, startup time, cost, queue depth and per-container CPU/memory. Those can follow. (The /metrics/* percentile endpoints are also behind a per-project feature flag, which is its own conversation.)

Two things worth reviewing

The endpoint's data arrays are not numbers. It relays raw query values, and those arrive as JSON strings, with null for padded gaps. The web client's (number | null)[] type is wrong about this — JS coerces on the way into the chart, so it never surfaced. Go doesn't, so MetricValue decodes from string, number or null and marshals back out as a plain number. NaN/±Inf decode as absent rather than blowing up json.Marshal.

Absence vs zero. A series that never reported prints -, not 0.00. A GPU row of 0.00 would claim we measured zero VRAM in use, which is a different statement from "no samples". A genuine measured 0 is still shown as 0.00; there's a test pinning that.

Also lifts normalizeAppID — which had been copy-pasted into three files — into api.NormalizeAppID, with its test moved alongside. Adding a fourth copy for this command seemed like the wrong direction.

Testing

go build, go vet, go test ./... all clean. No golden files regenerated. New unit tests cover MetricValue decoding (string/number/null/empty/NaN/Inf/garbage), number-form marshalling, window resolution, and the summary/column logic.

Verified against prod on a real H100 app over a window when it was actually serving:

• App scope returns Max/P50/P90 per metric. All three are equal here because the app ran a single replica — a quantile over one series is that series.
• Container scope was wrong in my first pass and is fixed here: the API names each metric's sole series after the metric (CPU, Memory, GPU), so matching cells to columns by name made Memory and GPU render - despite having data. Cells are now matched by position and the header collapses to PEAK. There's a regression test.
• GPU reads - for this app. The series are present but every sample is null, i.e. no GPU samples came back for that window — the web client sends identical params, so this is upstream, not a gap in the request. I could not verify a non-null GPU number, so if you have an app that reports VRAM it's worth a sanity check before merge.
• Bad --resolution, --start and --output values all produce clean validation errors; -o json piped with stdin closed is parseable (no spinner bytes).