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 { "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 { "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, or the units reference . Template variables Variables make dashboards reusable across environments and services. Query variable (populates from metric labels): { "name" : "job" , "type" : "query" , "datasource" : { "type" : "prometheus" , "uid" : "prometheus" } , "query" : { "query" : "label_values(up, job)" , "refId" : "A" } , "refresh" : 2 , "includeAll" : true , "multi" : true , "label" : "Service" } Constant variable: { "name" : "cluster" , "type" : "constant" , "query" : "production" , "label" : "Cluster" } Datasource variable (switch data sources without editing queries): { "name" : "datasource" , "type" : "datasource" , "pluginId" : "prometheus" , "includeAll" : false , "label" : "Prometheus" } Use variables in queries:
Reference a variable in a PromQL query
rate ( http_requests_total { job =~ "$job" } [ 5m ] )
Multi-value variable uses regex OR automatically
When $job = ["api", "worker"], it becomes job=~"api|worker"
Chain variables (second variable filters based on first): { "name" : "pod" , "query" : "label_values(kube_pod_info{namespace=\"$namespace\"}, pod)" } Transformations Transformations run client-side after data is fetched, reshaping results without changing queries. Common transformations: "transformations" : [ { "id" : "merge" , "options" : { } } , { "id" : "organize" , "options" : { "renameByName" : { "Value #A" : "Request Rate" , "Value #B" : "Error Rate" } , "excludeByName" : { "Time" : true } } } , { "id" : "calculateField" , "options" : { "alias" : "Error %" , "mode" : "reduceRow" , "reduce" : { "reducer" : "last" } , "binary" : { "left" : "errors" , "right" : "total" , "operator" : "/" } } } , { "id" : "filterByValue" , "options" : { "filters" : [ { "fieldName" : "Error %" , "config" : { "id" : "greater" , "options" : { "value" : 0.01 } } } ] , "type" : "include" , "match" : "any" } } ] Key transformation IDs: merge , organize , rename , calculateField , filterByValue , groupBy , sortBy , limit , labelsToFields , seriesToRows , partitionByValues . Dashboard linking Panel link (click a panel to go somewhere): "links" : [ { "title" : "Go to details" , "url" : "/d/details-dashboard?var-service=${__field.labels.service}" , "targetBlank" : false } ] Dashboard link (top-right corner links): "links" : [ { "title" : "Runbook" , "url" : "https://wiki.example.com/runbook/${job}" , "icon" : "external link" , "targetBlank" : true , "type" : "link" } ] Built-in variables for links: ${__value.raw} - current data point value ${__field.labels.job} - label value from current series ${__url.params} - current URL query parameters (pass-through) ${__from} / ${__to} - current time range as Unix ms Annotations Show events overlaid on time series panels (deployments, incidents, etc.). Query annotation from Loki: { "datasource" : { "type" : "loki" , "uid" : "loki" } , "expr" : "{job=\"deployments\"} |= \"deployed\"" , "name" : "Deployments" , "iconColor" : "blue" , "titleFormat" : "{{service}} deployed" , "textFormat" : "{{version}} by {{author}}" } Query annotation from Prometheus: { "datasource" : { "type" : "prometheus" , "uid" : "prometheus" } , "expr" : "changes(kube_deployment_status_observed_generation{namespace=\"production\"}[5m]) > 0" , "step" : "60s" , "name" : "Deployments" , "iconColor" : "blue" , "titleFormat" : "Deploy: {{deployment}}" } Dashboard via API
Create or update a dashboard
curl
-s
-X
POST
\
-H
"Authorization: Bearer
Get a dashboard by UID
curl
-s
-H
"Authorization: Bearer
Search dashboards
curl
-s
-H
"Authorization: Bearer
Create a folder
curl
-s
-X
POST
\
-H
"Authorization: Bearer