Grafana State Timeline and Status History Prompt

You are a senior observability engineer who visualizes discrete states in Grafana with State timeline (continuous state bars) and Status history (periodic status cells) panels.

I will provide:
- The metric representing state (0/1, enum codes, boolean, string)
- The entities (services, hosts, checks) as series
- The time granularity and what "good/bad" looks like

Your job:

1. **Pick the panel**: State timeline for continuous state that persists between changes (up/down, leader/follower); Status history for point-in-time samples on a fixed cadence (hourly check results).
2. **Shape the data**: return one series per entity with a numeric or string state field; use `Reduce`/`Group by` or `Prepare time series` (multi-frame) so each entity is its own row.
3. **Value mappings**: map raw values to labels+colors (`0→Down/red`, `1→Up/green`, `2→Degraded/orange`) — mappings drive the bar/cell colors.
4. **Thresholds vs mappings**: for numeric state use thresholds; for enum/string use value mappings; set `color.mode` accordingly.
5. **Merge consecutive**: enable `mergeValues` on state timeline so identical adjacent states collapse into one bar (cleaner, fewer segments).
6. **Row height + labels**: set `rowHeight`, `showValue` (auto/always/never), and legend to keep many entities readable.
7. **Alignment**: ensure the query step matches expectation — gaps render as null; use `connectNulls`/`No value` mapping to handle missing samples.
8. **Links**: add data links so clicking a state segment opens the entity's dashboard at that time (`${__url_time_range}`).

Mark DESTRUCTIVE: none — display-only. Flag if a null/missing state is mapped to a benign color, hiding real gaps.

---

State metric + values: [DESCRIBE]
Entities/series: [DESCRIBE]
Granularity + good/bad: [DESCRIBE]

Why this prompt works

State timeline and status history look interchangeable but model different things — persistent state versus periodic samples — and both hinge on value mappings and null handling. Mapping a missing sample to green hides an outage; using a timeline for sampled data implies continuity that isn’t real. This prompt picks the right panel, shapes one series per entity, and handles nulls honestly.

How to use it

1. Classify the data: persistent state vs periodic samples.
2. List all possible state values so none go unmapped.
3. Decide null handling explicitly — never map gaps to healthy.
4. Tune row height/merge for readability at scale.

Useful commands

# Inspect state-timeline mappings and options
curl -s -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/api/dashboards/uid/svc-states \
  | jq '.dashboard.panels[] | select(.type=="state-timeline") | {mappings:.fieldConfig.defaults.mappings, options:.options}'

Example config

State timeline for service health with merged states and honest null handling:

{
  "type": "state-timeline",
  "title": "Service Health Over Time",
  "targets": [
    { "refId": "A", "expr": "max by (service) (service_up)", "legendFormat": "{{service}}" }
  ],
  "options": {
    "mergeValues": true,
    "showValue": "auto",
    "rowHeight": 0.9,
    "legend": { "displayMode": "list", "placement": "bottom" }
  },
  "fieldConfig": {
    "defaults": {
      "color": { "mode": "thresholds" },
      "mappings": [
        { "type": "value", "options": {
          "0": { "text": "Down",     "color": "red",    "index": 0 },
          "1": { "text": "Up",       "color": "green",  "index": 1 },
          "2": { "text": "Degraded", "color": "orange", "index": 2 } } },
        { "type": "special", "options": {
          "match": "null", "result": { "text": "No Data", "color": "dark-purple", "index": 3 } } }
      ],
      "links": [
        { "title": "Service detail", "url": "/d/svc/service?var-service=${__field.labels.service}&${__url_time_range}" }
      ]
    }
  }
}

Common findings this catches

• Hidden outages → null mapped to green instead of No Data.
• False continuity → sampled data shown on a state timeline.
• Gray segments → a real state value left unmapped.
• Misleading gaps → query step mismatch.
• Lost flaps → mergeValues over-collapsed noisy state.
• Unreadable rows → too many series, no row-height tuning.

When to escalate

• SLO/availability semantics behind the states — service owner.
• Standardized health encoding across services — observability lead.
• Very high series counts needing pre-aggregation — platform team.