[Dashboards in chat] Additional guidance for agents regarding Metrics
- Dominant language
- TypeScript
- Stars
- 21.3k
- Forks
- 8.6k
- PR merge metrics
- PR metrics pending
Description
Add this guidance to both:
- [ ] Agent Builder in Kibana (both for dashboard generation and prettify)
- [ ] 3rd party skills
Metric decoration guidance:
Each decoration answers one question. Pick by question, not by aesthetics.
1. **Background trendline — "which way is it going?"** Use for unbounded metrics where the current value is meaningless without history: throughput, volume, latency, queue depth. Requires a time dimension with ≥12 buckets. Conveys direction only, never magnitude.
2. **Colour by value — "is this OK right now?"** Use only when (a) the metric has an agreed bad direction and (b) a defensible threshold exists. Good: error rate, SLO breach, failed jobs, replication lag. Never colour direction-neutral metrics (avg bytes, order size, session count) — it asserts a judgement the reader can't verify. Colour exceptions only; leave the rest neutral.
3. **Vertical bar vs. max — "how much headroom is left?"** Use only when a fixed, stateable ceiling exists: disk, memory, heap, pool, quota, rate limit, error budget. Mark warning/critical thresholds on the bar. Decide overflow behaviour explicitly. If the max is "highest seen recently," use the trendline instead.
4. **No decoration — the default** Start every tile plain. Add a decoration only when you can name both the question it answers and the reference point it answers against. If either is missing, leave it plain. Examples:
- The metric is a reference fact, not a judgement (total records, node count) — no direction, no ceiling.
- None of the three preconditions hold: no time series, no threshold, no fixed max. Don't pick the least-bad option; pick none.
- The data is thin or noisy — few buckets, small denominators.
- Other tiles are already decorated. Decoration is scarce per dashboard, not per tile.
- The reader can't act on it.
**Combining**
- Colour + bar: good. Colour the bar, not the number.
- Trendline + bar: avoid. Conflicting reference frames.
- Per row of tiles, decorate at most one or two. If everything is red and barred, nothing stands out.
Contributor guide
Assessment
This issue has not been assessed yet.