elastic / elastic/kibana

[Dashboards in chat] Additional guidance for agents regarding Metrics

Open
#291,033 1 comment 0 reactions 0 assignees View on GitHub
Team:Presentation
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.

Image

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.