.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
Grafana ships with no dashboards of its own. You get an empty Dashboards page, a data source list you have not filled in yet and a blue plus sign. Everything past that point is something you built or something you imported.
This covers the whole surface. What a dashboard is as a stored object, building one panel at a time, template variables, importing from the community library and keeping the JSON somewhere sane once you have more than a handful. Grafana 13.2 is current as of writing, and both the layout engine and the editing model changed in 13, so plenty of the screenshots elsewhere on the web no longer match your screen.
What a Grafana dashboard stores
A dashboard is a JSON document sitting in Grafana's own database. It holds the panels, the query attached to each one, the visualisation options, the grid coordinates, the variable definitions and a default time range. What it does not hold is a single data point. The docs define a dashboard as "a set of one or more panels, organized and arranged into one or more rows or tabs, that provide an at-a-glance view of related information", and every panel fires its query fresh the moment the page loads.
A dashboard is a saved question. Backups are therefore a JSON problem, since copying the JSON copies the dashboard, and dropping it onto a clean instance gives identical panels as long as the data sources resolve there. An empty dashboard is usually a data source problem: if every panel reads No data at once, the query is reaching nothing.
Retention has nothing to do with Grafana either. How far back a panel draws is decided by Prometheus, Loki or whatever else is behind it, so widening the time picker past your retention window gives you a graph starting partway across the screen. The Grafana setup guide covers where those pieces sit relative to each other, which is the confusion underneath a lot of this.
Create a dashboard and add the first panel
Click Dashboards in the main menu, click New and select New dashboard. You get an empty canvas with an Add new element icon, which is the blue plus sign. Click it and either click or drag a panel onto the dashboard.
Pick a data source and write a query
Grafana offers Configure visualization, which opens panel edit mode with the default data source for your instance already selected. Change it at the top of the query editor if that is not the one you meant. The other options are Use saved query, an Enterprise and Cloud feature, and Use library panel.
The editor changes shape depending on what you picked. Prometheus gives you Builder and Code modes. SQL data sources give a text area plus macros like $__timeFilter that expand into the dashboard time range. Click Refresh to run the query and watch the result land in the preview above.
Choose a visualisation and save
The visualisation picker sits at the top right and defaults to Time series, correct for most queries returning a timestamp and a number. The Suggestions tab inspects the shape of your data and proposes panels that fit, which helps on awkward cases like a query returning one row of strings.
Click Save dashboard, give it a title and pick a folder. That folder choice matters more than it looks, because permissions attach to folders and dashboards inherit them. Dropping everything into the default folder means untangling it later when someone asks for read-only access to the database dashboards and nothing else.
Grafana panel types and when to pick each
Grafana 13 ships a bit over two dozen built-in visualisations plus a small set of widgets. These are the ones that carry the weight on infrastructure and application dashboards.
| Panel | What it's for |
|---|---|
| Time series | The default, and correct for anything with a timestamp on it. Lines, bars or points, with per-series overrides for units, colour and axis placement. |
| Stat | One large number with an optional sparkline behind it. A whole guide to Stat panel deltas exists because the reducer decides what that number means and picking the wrong one is so common. |
| Gauge | A single value drawn against a minimum, a maximum and thresholds. Good for a bounded percentage, useless for anything with no natural ceiling. |
| Bar gauge | The gauge idea rendered as bars, so it handles twenty series in the space a gauge gives to one. This is the panel for per-host disk usage. |
| Table | Raw rows, or one reduced value per series, with formatting and cell colouring per column. What you build when someone wants to sort by a number. |
| Heatmap | Distribution over time. Buckets on the y axis, colour for how many samples landed in each. A native fit for Prometheus histograms and the honest way to show latency. |
| Logs | Log lines from Loki or Elasticsearch, filtered by the query's label selectors. The Grafana logs walkthrough covers the source side. Pairs with a graph above it so you can click a spike and read the cause. |
| State timeline | Discrete states over time as coloured bands. Up and down, deploy state, alert state. |
| Bar chart | Categorical data where the x axis is not time. One bar per category. |
| Histogram | Distribution of values across a single bucketed chart, with time collapsed away. |
| Trend | Time series drawing for an x axis that increases without being a clock. Build number, engine RPM, request sequence. |
| Text | A widget rather than a visualisation. Markdown or HTML for the paragraph explaining who owns this dashboard. |
The rest covers narrower ground: Pie chart, Candlestick, XY chart, Geomap, Canvas, Node graph, Traces, Flame graph and Status history, plus a handful of widgets.
Pie charts work for four categories summing to something meaningful and fail everywhere else, because what you want on a monitoring dashboard is change over time and a pie chart destroys that by definition. I use a bar gauge every time and have never regretted it.
Dashboard layout, rows and tabs
Panels group into rows or tabs, both reached from the Add new element menu as Add row or Group into rows and Add tab or Group into tabs. Rows are horizontal sections with a title you click to collapse. Tabs arrived in Grafana 13 and split a dashboard into views sharing one time picker and one set of variables.
Rows earn their keep through collapsing. Panels inside a collapsed row are not rendered, so a forty-panel dashboard where thirty live in collapsed rows behaves like a ten-panel one on load. Put what you check daily at the top and name the rest.
Custom layout and auto grid
A dashboard has two layout modes. Custom lets you "position and size panels individually" and is "the default selection for a new dashboard". Auto grid makes panels "resize and fit automatically to create a uniform grid", and the docs are explicit that you "can't make manual changes to this layout".
Auto grid suits a wall of similar panels, like eight bar gauges showing one metric across eight hosts. Custom is what you want the moment a graph needs to be twice as wide as its neighbours, which describes most real dashboards. Switching to auto grid discards your sizing, so decide before spending twenty minutes dragging corners.
Repeat a panel or a row over a variable
In panel edit mode expand Repeat options, set Repeat by variable and choose Horizontal or Vertical. Grafana renders one copy per selected value.
Rows repeat the same way and that is the more useful of the two. A row titled $host holding four panels, repeated over a host variable with All selected, gives you a complete per-host section for every machine from four panels of real configuration. The repeat only materialises after the dashboard reloads, so refresh the page before hunting for a bug.
Grafana variables
Template variables are the difference between one dashboard and forty near-identical ones nobody maintains. A variable is a named value the viewer picks from a dropdown, and queries, panel titles and repeats all reference it.
To add one, click Edit, then the Add new element icon, then Variable. There is also an Add variable plus sign at the top of the dashboard.
This part of the current UI irritates me daily. Variables and annotations used to live in dashboard settings, where every pre-13 tutorial still sends you, and they have moved into the editing sidebar. You now enter edit mode to read a variable someone else set up, on a dashboard you have no intention of changing.
The variable types
| Type | Documented purpose | Where it earns its place |
|---|---|---|
| Query | "The list of values comes from a data source query, such as server names, metric names, label values, or data centers." | Nearly always. On Prometheus that means label_values(node_uname_info, instance) and relatives. |
| Custom | "You want to define a fixed list of values manually." | Short fixed lists no query can produce, like a set of thresholds. |
| Text box | "Viewers need to enter a free-form value." | Search boxes over high-cardinality fields, like a request ID. |
| Constant | "A dashboard needs a reusable value that viewers don't change." | A metric path prefix that differs between instances. Hidden from viewers by default. |
| Data source | "Viewers need to switch a dashboard or query between data source instances." | One dashboard across several Prometheus servers, one per region. |
| Interval | "Viewers need to change the time grouping or aggregation interval in queries." | Widening an aggregation window without editing a query. Supports s, m, h, d, w, M and y. |
| Filters | "Viewers need dashboard-wide key/value filters for supported data sources." | Exploration where you do not know in advance which label matters. |
| Switch | "Display a switch that allows you to toggle between two configurable values for enabled and disabled states." | Flipping a query between two modes, like rate against raw counter. |
Filters is the old Ad hoc filters variable renamed and extended with grouping for Prometheus and Loki. The docs point out that the dashboard schema still calls it "kind": "AdhocVariable", so JSON you find in the wild uses the old name. It works on Prometheus, Loki, InfluxDB, Elasticsearch and OpenSearch.
Multi-value, Include All and the all value
Two toggles change how a variable behaves once it has more than one option. Multi-value "enables multiple values to be selected at the same time", and Include All option adds an All entry that selects everything.
What All sends to the data source surprises most people the first time. Grafana concatenates the options by default, which comes out as value1,value2,value3 for a CSV-shaped data source and as (host1|host2|host3) for Prometheus. In a URL the same selection appears as var-host=$__all, which is how you link to a dashboard with everything selected. If the concatenation is wrong for your query language, the Custom all value field takes a regular expression, a glob or Lucene syntax instead, and .* is the usual answer on Prometheus.
Your PromQL is where this bites. A single-value variable works fine as {instance="$instance"}. Turn on multi-value and that query breaks, because an exact match cannot match (host1|host2). Write {instance=~"$instance"} with the regex operator from the start and both cases work. This costs people an afternoon roughly once per career.
Turn on Include All only where "all of them at once" is a question worth answering. All hosts on a filesystem-usage bar gauge is useful. All hosts on one time series panel is twelve overlapping lines and an unreadable legend, where a repeated row would have served better.
Chained variables
A chained variable is a query variable whose query references another variable. The docs describe them as creating "dependent relationships where the options available in one variable depend on the selections made in another", and Grafana "automatically refreshes a variable when one of its linked variables change".
The standard shape is region then host. A region variable queries the distinct region labels and a host variable queries hosts filtered by region="$region", so picking a region shrinks the host list. Chain more than two deep and the reload cost stacks, since changing the first re-fires every query below it before any panel runs.
Each query variable also has a Refresh setting, on dashboard load or on time range change. The first is safer, because the second re-queries label values on every zoom.
$var, ${var} and [[var]] syntax
Grafana documents four ways to reference a variable, and the variable syntax reference is short enough to read in one sitting. That is not true of many doc pages.
| Syntax | Documented note |
|---|---|
$varname | "easy to read, but it doesn't allow you to use a variable in the middle of a word" |
${var_name} | "Use this syntax when you want to interpolate a variable in the middle of an expression" |
${var_name:<format>} | Advanced formatting control over the interpolated value |
[[varname]] | "Do not use. Deprecated syntax, that will be removed in a future release" |
Use $var for readability and ${var} whenever the variable butts up against other characters, which covers ${job}_total and any URL you build in a data link.
The format suffix goes undiscovered for years. ${hosts:pipe} gives host1|host2. ${name:sqlstring} quotes and escapes for SQL. ${var:raw} skips escaping entirely. Reach for sqlstring on any SQL data source where a viewer types into a text box variable, because a raw interpolation into a WHERE clause is exactly the injection you would expect.
Variables in panel titles
Panel titles interpolate. Set a title to CPU usage on $host and it tracks the dropdown, turning a repeated panel from eleven identical headings into eleven labelled ones. The same works in panel descriptions, text panels and dashboard links.
Import a dashboard from the grafana.com library
The grafana.com library holds thousands of dashboards published by Grafana Labs, exporter maintainers and anyone else who felt like it. Each has a numeric ID, and that ID is all you need.
Import by ID or by JSON
Click Dashboards in the primary menu, click New and select Import dashboard. Then do one of three things: "Upload a dashboard JSON file", "Paste a Grafana.com dashboard URL or ID into the field provided" or "Paste dashboard JSON text directly into the text area". Optionally change the name, folder or UID, select a data source if the dashboard asks for one, then click Import.
The data source mapping step
A published dashboard has no idea what your data sources are called, so its queries carry placeholder references. On import, in the docs' words, "Grafana lets you map those references to data sources that exist in your environment". You get one dropdown per placeholder, and this is the step that gets clicked through and then filed as a bug.
Click through too fast and you get a dashboard wired to nothing, or worse, wired to the wrong Prometheus, which looks like it works until the numbers disagree with reality. Dashboards pulling metrics from Prometheus and logs from Loki present several dropdowns and all of them need attention. Got it wrong already? Run the same import screen again rather than editing forty panels.
Two worth importing, and how to judge the rest
The Node Exporter Full dashboard, ID 1860, is the obvious first import, and the Prometheus walkthrough already covers it. So here are two different ones.
Prometheus 2.0 Overview, ID 3662, comes from Grafana Labs and monitors Prometheus itself using the metrics on its own /metrics endpoint. Import it on day one and you will know when your scrape is falling behind or when memory is climbing, the failures that make every other dashboard lie to you. It templates across multiple Prometheus servers if you run them.
Blackbox Exporter (HTTP prober), ID 13659, also from Grafana Labs, shows probe success, response time and certificate expiry for whatever URLs you point it at. It answers a question no host dashboard can, which is what somebody outside your network sees.
Before trusting anything else, check the revision date and changelog, because a dashboard last touched in 2019 targets metric names since renamed. Check the exporter version its description names. Check the job label it filters on, often hardcoded as job="node", which silently returns nothing if yours differs. Check the panel count, since sixty panels means sixty queries per refresh.
Should a beginner import or build? Import, read, then build. Community dashboards are the best PromQL teaching material available, since every panel exposes a working query written by somebody who knew the exporter. Spend an evening reading them, then build the six to eight panel dashboard you will keep open, by hand, with your own queries. The imported ones stay as reference.
Folders, tags and finding a dashboard again
Somewhere around thirty dashboards, search stops being optional. Folders nest four levels deep, and permissions live on the folder rather than the dashboard, granted to organisation roles, teams or individual users through Folder actions then Manage permissions. Dashboards inherit whatever the folder says.
One caveat from the docs: folder names cannot contain underscores, percentage signs or slashes if alert rules will live in them. I have not found an explanation for that anywhere. The docs state it and move on, and the failure when you ignore it is not obvious enough to enjoy.
Tags are the cross-cutting axis folders cannot give you, since a dashboard lives in exactly one folder and carries as many tags as you like. A folder per team or system, tags for what cuts across, like prod or oncall. Search filters on tags directly, and the dashboard finder opens with the f key.
On that note, Grafana has a decent set of keyboard shortcuts almost nobody uses. d then s opens dashboard settings, t then z zooms the time range out, p then s shares the panel under your cursor. Press ? for the full list. It will not change your life, and it does take about four seconds off every dashboard interaction you make for the rest of the year.
Star the four or five you use daily with Mark as favorite and they appear under Starred in the main menu. Deleted dashboards land in Recently deleted and stay recoverable for up to twelve months or a thousand dashboards, though a restored one comes back at version 1 without its dashboard-specific permissions. Deleted folders are gone immediately with no undo. Locking down who reaches any of this is covered in the Grafana security settings worth changing, and folder permissions are the part of it people set up last.
Dashboards as code
The JSON model
Dashboard settings has a JSON Model tab showing the whole thing. The fields to know are uid, the "unique dashboard identifier that can be generated by anyone" at 8 to 40 characters and stable across exports, templating holding your variable definitions, panels holding everything on screen, schemaVersion for the schema itself and version, which Grafana increments on every save.
Grafana 13 has three schema models in play. V2 Resource is current, V1 Resource covers Grafana 12.2.0 to 13.0.0 and Classic is everything before 12.2.0. Dynamic dashboards went generally available in 13, and the release notes say every new and existing dashboard moves to the new layout engine and schema automatically. The practical consequence: exports from a 13.x instance may not import cleanly into an older one, and Classic remains the format the community catalogue accepts.
Provision dashboards from files on disk
File provisioning reads dashboard JSON from a directory and keeps Grafana in sync with it. The provider config goes in /etc/grafana/provisioning/dashboards/ and the provisioning reference gives the shape:
apiVersion: 1
providers:
- name: 'a unique provider name'
orgId: 1
folder: ''
folderUid: ''
type: file
disableDeletion: false
updateIntervalSeconds: 10
allowUiUpdates: false
options:
path: /var/lib/grafana/dashboards
foldersFromFilesStructure: trueDrop dashboard JSON under that path, restart Grafana and it appears. updateIntervalSeconds controls how often Grafana rescans, ten seconds by default. foldersFromFilesStructure turns subdirectories into Grafana folders, the tidiest way to organise a growing set.
allowUiUpdates: false is the setting that generates support tickets. With it off, an edit made in the browser gets reverted on the next scan and whoever made it has no idea where their work went.
Running Grafana in a container makes the provisioning directory a volume mount and the dashboards directory another, which the Grafana Docker Compose setup covers as part of a full stack. Grafana 13 also made Git Sync generally available, storing dashboards in a GitHub, GitLab or Bitbucket repository and syncing both directions, so you get branches and pull requests on dashboard changes without maintaining the file layout yourself.
Database or files? Keep exploration in the database and promote anything more than one person depends on into provisioning. A dashboard that matters gets reviewed like code, survives a rebuilt instance and can be diffed when somebody moves a threshold. A dashboard you are still figuring out has no business being a pull request. Pushing over HTTP is the third option, and Grafana service accounts and API tokens covers the authentication for it. That route suits generated dashboards better than hand-written ones.
Export for another instance
Exporting gives you "a Grafana JSON file that contains everything you need", layout and variables and queries included. A toggle on that screen labelled Share dashboard with another instance will, per the docs, "remove details specific to your Grafana instance".
What it does is replace concrete data source references with an __inputs block and DS_ placeholders, the exact mechanism producing that dropdown on the import screen. Leave it off for your own backups, where you want the file to restore onto the same instance with nothing to click. Turn it on for anything going elsewhere.
Version history
Every save writes a version. Reach them from Edit, then the dashboard options icon, then Settings and the Versions tab. Grafana keeps 20 versions by default, adjustable through versions_to_keep under [dashboards]. Select two and click Compare versions for a plain-language summary, with View JSON Diff for the raw difference. Restore creates a new version holding the old content rather than deleting anything, so you can undo the undo.
Library panels
A library panel is a panel definition stored once and reused across dashboards, where editing the original updates every copy. Create one by hovering a panel in edit mode and choosing More then New library panel. Add one elsewhere through Use library panel and the Add panel from panel library drawer, and Unlink library panel cuts the connection again.
Use them sparingly. They are genuinely good for the one panel with fifteen field overrides you refuse to rebuild, and they turn into a nuisance when half a dashboard links to definitions living somewhere else, because the next person to edit it changes four dashboards without meaning to.
What makes a dashboard slow
Every panel is at least one query, and they fire together on load. Twenty panels means twenty concurrent queries, and if the target is a single Prometheus on a modest VPS, the problem is right there. Panel count is the first lever and the one people are most reluctant to pull.
Time range is the second. A panel running rate() over thirty days asks Prometheus to read thirty days of samples, and the cost scales with the range regardless of panel width. Set a sane default and let people widen it deliberately.
Under Query options, Max data points defaults to the panel's pixel width and Min interval "sets a minimum limit for the automatically calculated interval, which is typically the minimum scrape interval", corresponding to min step on Prometheus. Setting it to your scrape interval stops Grafana asking for resolution finer than the data can offer, removing a lot of pointless work across a wide dashboard.
High-cardinality variables are the quiet one. A query variable running label_values() over millions of series resolves before any panel runs, so a slow variable makes the whole dashboard slow to load even when every panel is fast. Constrain the variable query with a label filter rather than pulling every value.
Two things help and one does not. Collapsed rows keep their panels unrendered until opened, the cheapest fix available. The special Dashboard data source lets a panel reuse another panel's result: select it in the query editor and pick the source from the Use results from panel list, turning four panels sharing a query into one. What does not help is query caching, which the docs mark "Available in Grafana Enterprise and Grafana Cloud" and is therefore off the table on open source Grafana.
On dashboard size the docs are gentle, saying a dashboard "should tell a story or answer a question" and warning about cognitive load. I will be blunter. Past about a dozen panels a dashboard stops being read and starts being scrolled, and a screen where something is always slightly red teaches people that red means nothing. Six to eight panels visible without scrolling, everything else in collapsed rows, one dashboard per question. The dashboard best practices page also suggests prefixing throwaway dashboards with TEST or TMP and putting your name in the title so people know who to ask. That last one is free and it works.
To find out what a dashboard really costs you, open it with the browser network panel visible, press d then e to expand every collapsed row and count the requests that fire. On dashboards people inherited and never pruned, that number is routinely three figures.
