feat(metrics): harden metrics scripts and correct discovery-time docs

[Licenser]

Summary

Hardens the query-metrics / building-dashboards metrics scripts and fixes a documentation claim that contradicted actual behavior. All changes were verified live against the axiom deployment.

axiom-api

• Add --connect-timeout (10s) and --max-time (120s), overridable via AXIOM_CONNECT_TIMEOUT / AXIOM_MAX_TIME. Requests now fail fast instead of hanging indefinitely.

metrics-info

• URL-encode dataset, metric, and tag names plus time params (jq @uri) across all endpoint paths, so OTel names (/, ., spaces) and RFC3339 +offset survive reserved characters.
• Relative --start/--end (now, now-<N>[smhdw]), resolved to RFC3339 UTC client-side because the info endpoints only parse RFC3339.
• Concurrent per-tag value fetches in describe: collect → check all failures → then parse, so a failed fetch aborts loudly instead of emitting partial JSON.
• Fail-loud type probe: propagate query failures instead of swallowing them, so a failed probe is never misreported as the tag being "absent".

query-metrics/SKILL.md

• Document timeouts, single-quoting MPL, bounding group by cardinality, and 429 back-off.
• Correct the relative-time docs. Previously claimed metrics-info accepts "the same relative forms as metrics-query" — it does not. metrics-query forwards times to the server unparsed (broader grammar, e.g. now-1y), while metrics-info only handles now / now-<N>[smhdw] client-side.

Verification (against axiom deployment)

Form	metrics-query (server _mpl)	metrics-info
now-7d	OK	OK
now-1y	OK (server parses y)	400 (not in s/m/h/d/w)
now-1mo	400 (unexpected token "mo")	400 (RFC3339 parse error)

Also confirmed accurate against the live API and left unchanged: the {"code","message"} error shape + annotated MPL source-pointer, and the histogram bucket … using / quantile / temporality spec wording.

metrics-chart/SKILL.md

Test plan

• bash -n passes on both metrics-info copies and metrics-query
• Both metrics-info copies remain byte-identical
• Live re-run confirms docs match behavior (now-7d OK / now-1y 400 in info; now-1y OK in query)

🤖 Generated with Claude Code

---

Note

Low Risk
Mostly additive CLI/docs and local chart rendering; script changes improve URL safety and error handling without altering auth or query semantics.

Overview
Adds a new metrics-chart skill that turns metrics v2/v3 JSON into multi-series line charts (stdlib braille ASCII by default, optional gnuplot PNG/SVG/sixel, series collapse/top-N, agent-friendly PNG handoff), plus examples and unit tests. The root README lists the skill.

axiom-api (query-metrics and building-dashboards) now uses 10s connect / 120s total curl timeouts, overridable via AXIOM_CONNECT_TIMEOUT / AXIOM_MAX_TIME.

metrics-info (both skill copies) is hardened: URL-encoding for dataset/metric/tag names and time query params; client-side now / now-<N>[smhdw] normalization (narrower than metrics-query); parallel per-tag value fetches in describe with fail-fast on errors; tag type probes exit on query failure instead of reporting "absent".

query-metrics/SKILL.md documents MPL single-quoting, high-cardinality group by risk, histogram bucket guidance, corrected relative-time semantics for metrics-info vs metrics-query, timeouts, and 429 backoff.

^{Reviewed by Cursor Bugbot for commit d174ce6. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit c82aad1. Configure here.}