Grafana for Stream Deck — setup and support
Quick overview of what the plugin does and how the tiers split. The step-by-step setup walkthrough — token, instance, first key, troubleshooting — lives inside the plugin and always reflects the version you installed. How to open it.
Requirements
- Stream Deck app: 6.9 or later.
- OS: macOS 10.15+ or Windows 10+.
- Hardware: Stream Deck MK.2 / XL / Mini / Plus / Neo, or the Stream Deck Mobile app on iOS or Android.
- Grafana: any modern Grafana — OSS, Cloud, or self-hosted. Unified Alerting enabled if you want alert keys.
- Network: the host running the Stream Deck app must reach your Grafana over HTTP(S). Behind a corporate proxy or Cloudflare Access? Configure Custom Headers in the in-plugin Setup Guide.
Install
The recommended path is the Stream Deck Marketplace. Two listings — pick the tier you want.
From the Stream Deck Marketplace
- Open marketplace.elgato.com and search for
Grafana. - Pick Grafana (Free) or Grafana Pro (one-time purchase).
- Click Install — your Stream Deck app opens and adds the plugin.
- Both tiers can be installed at the same time. They show up as separate categories in the action sidebar (Grafana and Grafana Pro), so you can mix Free and Pro keys on the same deck.
Manual install (advanced)
If your environment can't use the Marketplace, drag a .streamDeckPlugin file directly onto the Stream Deck app icon. The plugin installs into the same per-user location the Marketplace uses. Marketplace updates supersede manually-installed copies.
Setup
The step-by-step walkthrough — Grafana service-account token, adding a Grafana instance, configuring your first key, troubleshooting, Custom Headers, TLS / Custom CA — lives inside the plugin. That way the guide always reflects what's actually shipping in the version you installed, and we don't end up with two copies that drift apart.
Opening the in-plugin Setup Guide
- Install the plugin (see Install above).
- Drop any Grafana action — Panel, Alert, or Logs — onto a Stream Deck key.
- Click the action. The Property Inspector opens at the bottom of the Stream Deck app window.
- Click the Setup Guide button at the top of the inspector.
It's the canonical source — updated with every release, and what we point support requests at.
Per-key customization (advanced)
Expand Per-Key Customization (Advanced) in the inspector to tune a single key. Some fields are Pro-only — see the homepage tier comparison for the full split.
Refresh Rate
How often this key polls Grafana. Default is the global 30 seconds. Pro can override per-key — drop to 10 seconds for a high-priority incident key.
Custom Label (Pro)
Override the panel's title with a shorter, screen-friendly name. Useful when the panel name is something like "API 5xx Rate — eu-west-1 prod cluster" and you just want "API errors."
Font Sizes (Pro)
Tune the title and value font sizes independently. Long values that overflow the key default get clipped — bump down by 1–2 points.
Inherit Panel Config
On by default. Applies the panel's unit, decimal places, and threshold colors from Grafana so the key matches the dashboard without manual re-entry. Turn it off if you want a plain key with no threshold tinting.
Thresholds (Pro)
Override the inherited thresholds. Mode is Absolute (fixed values like 50 / 90 for CPU%) or Percentage (0–100% of max). Below yellow → green, between yellow and red → yellow, above red → red.
Time Range (Pro)
Override the query window for this specific key — e.g. 6h for a wider sparkline or 5m for tight incident windows.
Gauge style (Pro)
Render as a stat key, a radial 270° gauge, or a 180° arc gauge. Match whichever your dashboard uses.
Trend arrows (Pro)
Show ▲ / ▼ with a delta value vs. the previous sample. Off by default.
Key interactions
Once configured, each key polls and renders independently. Press it for context:
- Short press — opens the panel's dashboard in your default browser.
- Long press (≥500ms) — cycles views: value → sparkline → combined → back. Pro keys with gauges cycle through gauge styles too.
Alerts
The Grafana Alert action has two modes:
- Single rule — pick one alert rule. The key shows that rule's state (firing / pending / normal) with a colored background.
- Active count — the key shows a number: how many rules across the instance are currently firing. Yellow threshold at N, red at M. Pending alerts show a corner badge. Style configurable on Pro: badge / label / ring / hidden.
Long-pressing a single-rule key opens the rule's view in your browser. Long-pressing a count key opens the alerting list filtered to state:firing.
Dial support (Stream Deck +, Pro)
Drop the Grafana Alert (Pro) action onto a dial slot on a Stream Deck +. The dial becomes a live browser of currently-firing alerts.
| Input | Behavior |
|---|---|
| Rotate | Browse next / previous firing or pending alert. Firing first, then pending. |
| Short press | Reserved for Stream Deck's own multi-action layer cycling — not bound by us, so it always works for layer swaps. |
| Long press | Force-refresh the alert list right now (don't wait for the next 30-second poll). |
| Touch tap | Open the currently-selected rule's Grafana page (Instances tab) in your browser. |
| Touch hold | Toggle the detail view — shows the labels that distinguish this firing instance from others under the same rule. |
Free vs Pro
Free covers the "I want a few panels glanceable" case. Pro covers the "I want the keys to match my dashboard ideology" case. The dividing line: does it let you bend the visual? It's probably Pro.
See the homepage tier comparison for the full matrix. Both tiers can be installed side by side; they appear as separate categories in the Stream Deck action sidebar.
Upgrade Free → Pro
- Install Grafana Pro from the Marketplace. You can leave Free installed.
- On any Free-tier key, open the inspector → Config (export / import) → Export. A JSON file downloads.
- On a Pro-tier key, inspector → Config (export / import) → Import. Pick the file.
- Pro reads the same settings shape and adds the Pro-only fields as defaults — your dashboard / panel / threshold mapping carries over.
About five minutes per key. No need to re-link to Grafana — the instances are stored at the global level and apply to both tiers.
Need help?
Setup or configuration questions
The in-plugin Setup Guide has the canonical troubleshooting steps for token errors, network issues, TLS, Custom Headers, and recovery after a system sleep. Open it the same way you would for first-time setup.
Bug reports and feature requests
Email support@madeathing.studio with: tier (Free or Pro), plugin version (Stream Deck app → Plugins → version field), Grafana version, OS, and what you expected vs. what you saw. Screenshots help.