Grafana for Stream Deck — setup and support
Plain, step-by-step install and configuration. Skip to Troubleshooting if something's wrong already.
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? See the Troubleshooting section.
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.
1. Create a Grafana service-account token
The plugin authenticates as a Grafana service account. Viewer role is enough. Don't reuse a personal API key — service accounts are revocable per device and scoped to read-only access.
- Log into Grafana as an admin. Open your Grafana instance in a web browser with administrator privileges.
- Navigate to Service Accounts. Go to Administration → Users and access → Service accounts.
- Create a new service account.
Click Add service account. Set:
- Name: a descriptive label such as
stream-deck - Role: Viewer (Editor / Admin not required and not recommended)
- Name: a descriptive label such as
- Generate a token.
Click into the new account → Add service account token. Set expiration per your policy.
A token starting with
glsa_will be generated. Copy this token immediately — Grafana shows it once.
Permissions needed
- Read on Dashboards — to enumerate dashboards and panels.
- Read on Alerting — for alert states and counts.
- Folder ACLs apply: the plugin sees exactly what the token sees.
2. Add the Grafana instance to Stream Deck
- Open the Property Inspector. Drag a Grafana Panel action onto any Stream Deck key. The Property Inspector opens on the right.
- Add an instance.
In the Grafana Instances section, click Add. Fill in:
- Name: a label like Production or Staging
- URL: the Grafana base URL, e.g.
https://grafana.example.com(no trailing slash, no path) - Token: paste the service-account token from step 1
- CF-Access ID & Secret: optional, only if your Grafana is behind Cloudflare Access (Pro only)
- Test the connection. Click Test Connection. A green dot + Grafana version means you're connected. If it fails, jump to Troubleshooting.
Multi-instance
You can add as many instances as you want. Free lets you switch which one is active. Pro lets each key target a different instance simultaneously — mix prod, staging, and your team's stack on one deck.
3. Configure your first key
- Search for a dashboard. In the Dashboards tab, type a name in the search box (it matches names and tags). Click the dashboard to load its panels.
- Pick a panel. The Panel dropdown populates with all panels in that dashboard. Supported types show a SUPPORTED tag. Pick the one with the metric you want.
- Pick a series. If the panel has more than one series, pick the specific one in the Series dropdown.
No query writing required
Browse — don't query. The plugin reads the panel's own query and extracts the current value automatically. Thresholds, units, and decimals come from the panel's Grafana config so the key matches the dashboard.
The key starts rendering within a few seconds of saving. Default poll is every 30 seconds.
4. 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.
Troubleshooting
Key shows "Error" (red icon)
The plugin couldn't fetch data from Grafana. Likely causes: Grafana is unreachable, the token has expired, or network connectivity is down. Click Test Connection in the inspector to verify. If the test passes but the key still shows an error, remove and re-add the key to restart polling.
Test Connection fails — 401 Unauthorized
The token is invalid or expired. In Grafana, go to Administration → Service accounts, find your Stream Deck account, and check the token expiration. Generate a new token and update the instance in the inspector.
Test Connection fails — 403 Forbidden
The service account lacks the right role. In Grafana → Administration → Service accounts, click your service account and confirm the role is Viewer or higher. Folder ACLs override role: if the dashboard you want is in a folder restricted to certain groups, add the service account.
Test Connection fails — network error or timeout
The Grafana URL is unreachable. Check (1) your internet connection, (2) the URL is correct and reachable from this machine, (3) any firewall or VPN rules. You can verify from a terminal:
curl -H "Authorization: Bearer glsa_YOUR_TOKEN" \
https://your-grafana/api/search?limit=1A JSON array response means the connection works at the network layer.
Grafana behind Cloudflare Access or proxy auth
Pro supports custom HTTP headers per Grafana instance. Add CF-Access-Client-Id and CF-Access-Client-Secret (or your equivalent) in the instance settings. Free doesn't expose this — you'd have to tunnel directly to Grafana from the host running Stream Deck.
Self-signed TLS or private CA
Not currently supported on either tier. The plugin uses Node's bundled root CAs. Workaround: terminate TLS on a reverse proxy with a public-CA cert, or add your internal CA to the host's system trust store before launching Stream Deck.
No dashboards appear in search
Either there are no dashboards in your Grafana, or the service account can't read them. Confirm (1) you can see dashboards as a regular user in the Grafana web UI, (2) the service account role is Viewer or higher, (3) click Refresh Dashboards in the inspector to force a reload.
Panel renders the wrong series
Multi-series panels expose a Series dropdown in the inspector. Pick the one you want. On Pro, you can also override the title with a Custom label so the key shows what's meaningful instead of the panel's verbose name.
Value or threshold colors look wrong
The plugin inherits thresholds and units from the panel's own Grafana config. If they look wrong, check the panel in Grafana — the plugin is probably right and the panel has stale or misconfigured thresholds. On Pro, you can override thresholds per key.
Key shows "No data"
The query returned an empty result for the current time range. Common causes: the metric stopped reporting, the panel's time range doesn't intersect with the data, or the data source itself is unreachable from Grafana. Verify in Grafana first.
Metric value is stale or not updating
Check the refresh interval — if it's set very high (e.g. 10 minutes) the value will lag. Also: if your Grafana datasource (Prometheus, Loki, etc.) is slow to respond, the next poll waits for it. Try lowering the refresh interval to 30 seconds for a quick test.
Long press doesn't cycle views
The long-press detector requires holding for at least 500 ms. Try a full second to be sure. If it still doesn't register, Stream Deck hardware timing varies slightly between models — try a slightly longer hold.
Long alert names get cut off on the key
Use Custom label (Pro) to override the rule name with something shorter. Font sizes for title and value are also tunable per key on Pro.
Plugin stops rendering after a system sleep
Rare, usually resolves on the next 30-second poll. If it doesn't: right-click the action → Remove, then drag it back onto the key. As a heavier fix, quit and reopen the Stream Deck app to restart the plugin host.
I want to file a bug or feature request
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.