grafana-dashboard-designer

name	grafana-dashboard-designer
description	Create, optimize, export, prepare, and import Grafana dashboards. Use for selecting reusable dashboard templates, generating Grafana JSON, configuring Prometheus/Loki/VictoriaLogs/MySQL/Elasticsearch data sources, discovering metrics, designing panels and variables, validating dashboards, or deploying dashboards through the Grafana HTTP API.

Grafana Dashboard Designer

Create importable Grafana JSON with clear information hierarchy, correct queries, semantic thresholds, maintainable variables, and explicit deployment safety.

Workflow

1. Clarify the monitored system, audience, data sources, target Grafana folder, and whether the request is create-only or includes import.
2. Search the bundled catalog before building from scratch:

   scripts/grafana_dashboard.py list --query kubernetes
   scripts/grafana_dashboard.py list --category 03
   

3. Load only references/template-index.json and the selected template. Choose the closest dashboard by category, panel types, variables, and data-source types.
4. Discover target data-source and folder UIDs, then query available metrics before editing queries:

   scripts/grafana_dashboard.py discover --base-url "$GRAFANA_URL" > /tmp/grafana-targets.json
   curl -s "$PROMETHEUS_URL/api/v1/label/__name__/values" | jq -r '.data[]'
   curl -sG "$PROMETHEUS_URL/api/v1/series" --data-urlencode 'match[]=metric_name' | jq
   

5. Prepare a copy with a new title, data-source selections, and environment replacements:

   scripts/grafana_dashboard.py prepare 01-08 \
     --title "Platform Cluster Overview" \
     --datasource prometheus=prometheus-uid \
     --replace prod-cluster=target-cluster \
     --output /tmp/platform-cluster.json
   

6. Validate with jq empty, inspect unresolved example values, and review every query and variable against live labels.
7. Import only when the user explicitly requests deployment and confirms the exact Grafana URL, folder UID, title, overwrite behavior, and command. Read references/grafana-api.md before any API write.

Template Library

The library contains 69 sanitized dashboards exported from nine operational categories:

Category	Focus	Templates
01	Kubernetes and hosts	10
02	Network and gateways	6
03	Storage	11
04	Logs	11
05	Databases	10
06	Middleware	8
07	GPU	4
08	CI/CD	4
09	Model serving	5

Templates use ${DS_PROMETHEUS}, ${DS_LOKI}, ${DS_VICTORIALOGS}, ${DS_MYSQL}, and ${DS_ELASTICSEARCH} variables instead of fixed data-source UIDs. RFC 5737 addresses and example-* names are redacted placeholders; replace them before import.

Layout

When adapting a template or starting from references/dashboard_template.json:

• Top: 3-6 Stat/Gauge panels for health, saturation, traffic, and errors.
• Middle: Time Series panels for trend and correlation.
• Bottom: logs, events, and details only when they help diagnosis.
• Use ${datasource}-style variables, timezone: browser, and refresh intervals of 30 seconds or slower.

Grafana API Safety

• Use GRAFANA_URL and read GRAFANA_TOKEN from the environment. Never print or persist the token.
• Treat search, dashboard GET, folder GET, data-source GET, and health endpoints as read-only.
• Treat dashboard import, overwrite, delete, folder creation, permission changes, and data-source changes as mutating.
• Before a mutation, show the exact command, target URL and folder, dashboard title, overwrite flag, and expected effect; wait for a second explicit confirmation.
• Pass --yes only after confirmation. The CLI rejects imports without it.
• Never import a template with unresolved data-source variables, example addresses, example names, or unreviewed queries.

Design Rules

• Keep the first screen actionable: status, capacity, traffic, errors, and the most likely next clue.
• Use consistent colors: healthy green #22c55e, warning yellow #f59e0b, critical red #ef4444, unknown gray #6b7280.
• Use dark theme colors only for NOC/large-screen/night scenarios; otherwise prefer light theme.
• Use multi-series tooltip and useful legend stats: mean, max, lastNotNull.
• Avoid high-cardinality queries, excessive refresh, and panels that duplicate the same signal.

Metric Hints

• Kubernetes: kube_pod_*, kube_node_*, container_*.
• Aliyun CloudMonitor format: Aliyun{Product}_{Metric}.
• Common Aliyun prefixes: AliyunEcs_, AliyunRds_, AliyunSlb_, AliyunPolardb_, AliyunKvstore_, AliyunKafka_, AliyunFlink_, AliyunSelectdb_.
• Common labels: instanceId, clusterId, userId, k8s_cluster, namespace, pod, node.

JSON Defaults

{
  "title": "Dashboard Title",
  "tags": ["monitoring"],
  "timezone": "browser",
  "editable": true,
  "graphTooltip": 1,
  "refresh": "30s",
  "schemaVersion": 39,
  "time": { "from": "now-3h", "to": "now" },
  "templating": {
    "list": [
      { "name": "datasource", "type": "datasource", "query"  
    
  
   

Use datasource references like:

{ "datasource": { "type": "prometheus", "uid": "${datasource}" } }

Thresholds And Mappings

Use absolute thresholds unless the metric is naturally percentage based:

{
  "thresholds": {
    "mode": "absolute",
    "steps": [
      { "color": "#22c55e", "value": null },
      { "color": "#f59e0b", "value": 70 },
      { "color": "#ef4444", "value": 85 }
    ]
  }
}

Useful units: percent, percentunit, bytes, binBps, ms, s, iops, reqps, short, none.

References

Load only the file needed for the task:

• references/panel_templates.md: reusable panel JSON.
• references/panel_types.md: panel-specific options.
• references/layout_system.md: dashboard layout choices.
• references/color_system.md or references/dark_theme.md: theme details.
• references/performance.md: query and dashboard performance.
• references/advanced_features.md: variables, transformations, links, annotations, alerts.
• references/troubleshooting.md: import or rendering problems.
• references/grafana-api.md: authenticated API discovery, preparation, import, and rollback.
• references/template-index.json: searchable metadata for all 69 bundled templates.
• references/templates/: sanitized dashboard JSON; load only the selected file.
• references/dashboard_template.json, references/dark-theme-template.json: starter JSON.
• references/aliyun-ecs-dashboard.json, references/aliyun-selectdb-dashboard.json: examples.