grafana-dashboard-optimize

What this skill does

# Grafana Dashboard Content Optimization (Observability / SRE)

Audit and optimize dashboard content for observability best practices. Apply RED/USE/Golden Signals methodology, improve diagnostic value, and reduce cognitive load for on-call teams.

**Not suitable for**: Code structure refactoring (use `grafana-jsonnet-refactor`), initial JSON conversion (use `grafana-json-to-jsonnet`), or code style formatting.

## Workflow with progress tracking

Copy this checklist and track your progress:

```
Optimization Progress:
- [ ] Step 1: Understand context (purpose, audience, strategy)
- [ ] Step 2: Run seven-dimensional content audit
- [ ] Step 3: Produce prioritized recommendations report
- [ ] Step 4: Apply changes (if requested)
- [ ] Step 5: Validate improvements
```

**Step 1: Understand context**

Before any edits, document:
- Dashboard purpose and target audience (SRE/on-call/management)
- Current monitoring strategy and key questions it should answer
- Datasources, variables, time range settings
- Row structure and panel organization
- Annotations, dashboard metadata (`__inputs`, `__requires`, `schemaVersion`, `graphTooltip`, `version`), and pluginVersion

See `references/full-optimization-playbook.md` for detailed context gathering.
If optimizing dashboards in a specific repo or stack, review local Jsonnet defaults and docs in the working directory for current conventions.

**Step 2: Run seven-dimensional content audit**

Audit across these dimensions:
1. **Panel semantics**: Missing/duplicated views, diagnostic coverage
2. **Query optimization**: rate/increase usage, aggregation, cardinality
3. **Variable design**: Names, defaults, cascading relationships
4. **Visualization**: Panel types, units, thresholds, legends, table field pruning
5. **Layout**: Overview → symptoms → root cause flow
6. **Titles/descriptions**: Unified title style, clarity, context, troubleshooting hints, every panel has a description
7. **Proactive additions**: SLO/SLI, annotations, comparisons, runbooks, dashboard metadata parity

For the full audit checklist and visualization/layout guidance, see `references/full-optimization-playbook.md`.
For observability strategies (RED/USE/Golden Signals), see `references/observability-strategies.md`.
For color, thresholds, and table styling aligned with local repo conventions, see `references/visual-style-guides.md`.

**Step 3: Produce prioritized recommendations**

Create structured assessment report with:
- **Critical**: Missing essential metrics, broken queries, misleading visualizations
- **Recommended**: Important improvements with clear ROI
- **Optional**: Nice-to-have enhancements

Include rationale and expected impact for each recommendation. Use template in `references/report-template.md`.

**Step 4: Apply changes (if requested)**

If user approves changes:
- Use available unified libraries when present (commonly `panels`, `standards`, `themes`)
- Keep code structure changes minimal (content-only optimization)
- Include Jsonnet snippets for high-impact changes
- Preserve datasource selection patterns and any `__inputs` / `__requires` blocks if present
- Preserve `schemaVersion`, `graphTooltip`, `version`, and `pluginVersion` when present
- Add or improve panel descriptions so every panel has a clear, actionable description
- Match existing repo/dashboard structure (imports → config → constants → helpers → panels → rows → variables → dashboard)
- For **table** panels, use the `panels` lib (no raw Grafonnet) and follow the detailed table guidance in `references/full-optimization-playbook.md`.

For query optimization patterns, see `references/query-optimization.md`.

**Step 5: Validate improvements**

Run the quality checklist below against the improved dashboard. If any check fails, return to Step 4, fix, and verify again.

## Quality checklist

- [ ] RED/USE/Golden Signals coverage is complete
- [ ] Queries are efficient and bounded
- [ ] Units and thresholds use `standards.*`
- [ ] Panel titles are consistent and every panel has a clear, actionable description
- [ ] Layout follows overview → symptoms → root cause
- [ ] Table panels remove unused fields (overrides/thresholds, colors, widths, cell types applied)
- [ ] Variables return values and have no duplicates/extras
- [ ] Regex filters preserved or added where needed
- [ ] Row membership is correct (panels align to row `gridPos.y`)
- [ ] `__inputs` / `__requires`, annotations, and dashboard metadata remain valid and intentional

## Guardrails

- Do not refactor code structure; use `grafana-jsonnet-refactor` for that.
- Avoid broad rewrites; focus on content quality and observability value.
- Keep deep guidance in `references/` instead of bloating this file.
- Do not run `jsonnetfmt` / `jsonnet fmt` on generated Jsonnet files.

## References (load as needed)

- `references/visual-style-guides.md`
- `references/full-optimization-playbook.md` for the complete framework
- `references/observability-strategies.md` for RED/USE/Golden Signals
- `references/query-optimization.md` for PromQL/SQL guidance
- `references/report-template.md` for the assessment report format