Dashboarding

# Grafana Dashboard Authoring

Dashboards are JSON documents stored in Grafana. Every dashboard has panels, variables, time
range, and refresh settings. Understanding the JSON schema lets you programmatically create and
modify dashboards via the API or Grafana Assistant tools.

---

## Dashboard JSON structure

```json
{
  "title": "My Dashboard",
  "uid": "my-dashboard-v1",
  "tags": ["service", "production"],
  "time": { "from": "now-1h", "to": "now" },
  "refresh": "30s",
  "timezone": "browser",
  "schemaVersion": 41,
  "templating": { "list": [] },
  "annotations": { "list": [] },
  "panels": []
}
```

**Key fields:**
- `uid` - stable identifier used in URLs and API calls; keep it short and meaningful
- `schemaVersion` - use `41` for Grafana 11+
- `time.from` / `to` - supports relative (`now-1h`, `now-7d`) and absolute ISO timestamps
- `refresh` - auto-refresh interval (`"30s"`, `"1m"`, `"5m"`, `""` for off)

---

## Panel types and when to use them

| Panel | Use case |
|---|---|
| **Time series** | Any metric over time; the default choice for counters, rates, gauges |
| **Stat** | Single current value with optional sparkline (e.g. uptime, current RPS) |
| **Gauge** | Percent or value against a min/max (e.g. disk usage %) |
| **Bar gauge** | Compare multiple values side by side (e.g. top 10 services by RPS) |
| **Table** | Multi-column data (e.g. alert list with labels) |
| **Heatmap** | Distribution over time (e.g. request duration histogram) |
| **Logs** | Loki log streams |
| **Traces** | Tempo trace search |
| **Text** | Markdown documentation panels |
| **Candlestick** | OHLC/financial data (or min/max/avg patterns) |
| **Node graph** | Service dependency graphs |

---

## Panel JSON structure

```json
{
  "id": 1,
  "type": "timeseries",
  "title": "Request Rate",
  "gridPos": { "x": 0, "y": 0, "w": 12, "h": 8 },
  "datasource": { "type": "prometheus", "uid": "${datasource}" },
  "targets": [
    {
      "expr": "sum(rate(http_requests_total{job=\"$job\"}[5m])) by (status_code)",
      "legendFormat": "{{status_code}}",
      "refId": "A"
    }
  ],
  "fieldConfig": {
    "defaults": {
      "unit": "reqps",
      "thresholds": {
        "mode": "absolute",
        "steps": [
          { "color": "green", "value": null },
          { "color": "yellow", "value": 1000 },
          { "color": "red", "value": 5000 }
        ]
      }
    },
    "overrides": []
  },
  "options": {
    "legend": { "calcs": ["mean", "max", "last"], "displayMode": "table", "placement": "bottom" },
    "tooltip": { "mode": "multi", "sort": "desc" }
  }
}
```

**`gridPos`:** The dashboard uses a 24-column grid. Common widths: full-width=24, half=12, third=8, quarter=6. Height in grid units (1 unit ≈ 30px).

---

## Useful unit identifiers

```
# Rates
"reqps"      -- requests per second
"ops"        -- operations per second
"Bps"        -- bytes per second
"percentunit" -- 0.0-1.0 as percentage

# Storage
"bytes"      -- bytes (auto-scales to KB/MB/GB)
"decbytes"   -- decimal bytes (1 KB = 1000 B)

# Time
"ms"         -- milliseconds
"s"          -- seconds
"dtdurationms" -- duration in ms (shows as "1h 2m 3s")

# Counts
"short"      -- compact number (1.2k, 3.4M)
"none"       -- raw number
```

Full list: **Panel > Field > Unit** dropdown in Grafana UI