Grafana and InfluxDB
Visualize stored MQTT payload history in Grafana. iShareRadio offers hosted Grafana tied to your portal account, or you can connect your own Grafana (cloud or self-hosted) using an Influx read token from the portal.
| Option | Best for |
|---|---|
| Hosted Grafana | Sign in to the portal and open Dashboards — datasource and starter dashboard are already provisioned |
| Connect your own Grafana | Grafana Cloud, an existing Grafana server, or a separate team instance — you configure the Influx data source yourself |
Both options read the same stored history in InfluxDB for your account. Grafana connects to Influx only — not the portal REST API.
| What | Where |
|---|---|
| MQTT SaaS portal | Your portal URL (e.g. https://mqtt.ishareradio.com) |
| Hosted Grafana (production) | https://mqtt-grafana.ishareradio.com/ |
| Influx read token (BYOG only) | Settings → Grafana / Influx tokens |
| Influx API URL for BYOG | Shown in the create-token dialog (HTTPS on port 443 in production) |
What you need first
- An active subscription with stored history (non-zero retention days on your plan).
- At least one MQTT client that has published telemetry (so there is data to query).
- One Grafana add-on under Subscriptions (you do not need both):
- Hosted Grafana — Hosted Grafana dashboard
- Connect your own Grafana — Grafana / Influx integration (Influx read tokens in Settings)
For hosted Grafana, sign in to the portal and open Dashboards — no Influx token setup.
For your own Grafana, create an Influx read token in Settings, then allow HTTPS from your Grafana host to the Influx URL in the dialog. Do not use your MQTT password in Grafana.
Hosted Grafana
When your history bucket is first provisioned, the platform creates a dedicated Grafana organization for your account (same mqtt-… name as your Influx org). Portal provisioning adds:
| Item | Description |
|---|---|
| Data source | MQTT History — InfluxDB Flux, scoped to your org and bucket |
| Dashboard | MQTT History Overview — message rate, breakdown by client, recent previews |
Each account’s dashboards, users, and datasource settings are isolated on the hosted Grafana service. You can create additional dashboards and folders in your org like any other Grafana tenant.
Open hosted Grafana
- Sign in to the MQTT portal and select your tenant (if you belong to more than one).
- Click Dashboards in the sidebar.
You are redirected to hosted Grafana for your tenant org via portal SSO — no Influx token setup required.
You can also bookmark https://mqtt-grafana.ishareradio.com/ after your first visit. You must stay signed in to the portal (same browser session) for SSO to work.
Roles on hosted Grafana
Portal membership maps to Grafana roles in your tenant org:
| Portal role | Hosted Grafana role |
|---|---|
| Owner, Member | Editor — view and edit dashboards |
| Data manager | Viewer — view dashboards only |
Team members who are not signed in to the portal cannot access your hosted org.
Starter dashboard vs custom work
MQTT History Overview is a starting point. Use Explore or New dashboard in hosted Grafana to build additional panels. Flux query examples that apply to both hosted and BYOG Grafana are in Example Flux queries below.
If you prefer Grafana Cloud or an existing Grafana server, use Connect your own Grafana instead — hosted and BYOG can be used in parallel.
Connect your own Grafana
Use this path when Grafana runs on your infrastructure (Grafana Cloud, homelab, corporate Grafana, and so on). Create a read-only InfluxDB token in the portal and add an InfluxDB data source in your Grafana instance.
Step 1 — Create an Influx read token
- Sign in to the MQTT portal and open Settings.
- In Grafana / Influx tokens, optionally enter a label (e.g.
Grafana home). - Click Create token.
- Copy the token and connection details from the dialog before you close it (password manager). The portal does not show the token again later.
Use Copy as: .env file for environment variables, or Grafana datasource for a provisioning YAML snippet (provisioning/datasources/ on your Grafana server).
Record these fields from the dialog:
| Field | Notes |
|---|---|
| Influx token | API token for Grafana only — not a REST API token |
| Influx URL | Use the exact URL from the dialog (production: HTTPS on 443) |
| Organization | Your tenant Influx org (mqtt-… from the dialog) |
| Bucket | Opaque name unique to your account (e.g. b_…) |
| Measurement | mqtt_saas_payload |
You may have up to 10 active read tokens. When creating a token, choose an expiry (or Never). The table shows Expires and Last seen (approximate, from Influx metadata). Use Edit label or Regenerate token (new token value in the dialog only) like other credential tables. Revoke unused tokens when you rotate credentials.
See Influx organization for how tenant org names relate to your account.
Step 2 — Add an InfluxDB data source in Grafana
These steps match Grafana 10+ with the InfluxDB data source and Flux query language.
- In Grafana: Connections → Add new connection (or Configuration → Data sources → Add data source).
- Choose InfluxDB.
- Configure:
| Setting | Value |
|---|---|
| Query language | Flux |
| URL | Influx URL from the token dialog |
| Organization | Organization from the dialog |
| Token | Influx read token from the dialog |
| Default bucket | Bucket name from the dialog |
- Click Save & test. You should see a successful connection.
Treat the Influx token like a password — do not commit it to git or share it in tickets.
Example Flux queries
In Grafana, open Explore, select your InfluxDB data source, and run Flux queries. Replace YOUR_BUCKET with the bucket from your token dialog (BYOG) or from Settings → Grafana / Influx tokens / portal overview (hosted — same bucket for your account).
The topic tag on each point is always the platform path ({account_id}/{client_id}/…). Prefer r.account_id == "…" in Flux; optionally r.topic =~ /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\// — see MQTT clients — platform layout.
Recent payloads (last 24 hours)
from(bucket: "YOUR_BUCKET")
|> range(start: -24h)
|> filter(fn: (r) => r._measurement == "mqtt_saas_payload")
|> filter(fn: (r) => r._field == "payload")
|> limit(n: 20)
Filter by MQTT client client_id
from(bucket: "YOUR_BUCKET")
|> range(start: -24h)
|> filter(fn: (r) => r._measurement == "mqtt_saas_payload")
|> filter(fn: (r) => r._field == "payload")
|> filter(fn: (r) => r.client_id == "your-client-id")
|> limit(n: 50)
Filter by account_id
from(bucket: "YOUR_BUCKET")
|> range(start: -24h)
|> filter(fn: (r) => r._measurement == "mqtt_saas_payload")
|> filter(fn: (r) => r._field == "payload")
|> filter(fn: (r) => r.account_id == "550e8400-e29b-41d4-a716-446655440000")
|> limit(n: 50)
Message count per hour by client_id (dashboard-friendly)
from(bucket: "YOUR_BUCKET")
|> range(start: v.timeRangeStart, stop: v.timeRangeStop)
|> filter(fn: (r) => r._measurement == "mqtt_saas_payload")
|> filter(fn: (r) => r._field == "payload")
|> aggregateWindow(every: 1h, fn: count, createEmpty: false)
|> group(columns: ["client_id"])
If a query returns no data, confirm devices have published within the time range and that retention has not expired.
Tags and fields on each point
| Tag / field | Meaning |
|---|---|
client_id |
MQTT client id (portal MQTT Clients row) |
device_id |
Internal device id |
topic |
Platform storage topic ({account_id}/{client_id}/…; normalized from wire on ingest) |
account_id |
Your account UUID |
mqtt_qos / effective_qos |
QoS on the wire / after policy |
payload |
Full payload (often JSON text) |
preview |
Truncated preview string |
Revoke or rotate a token (BYOG)
Hosted Grafana does not use portal Influx read tokens — skip this section unless you connect your own Grafana.
- Settings → Grafana / Influx tokens → Revoke on the row you want to retire.
- Create token again and update the Grafana data source Token field → Save & test.
- Revoke the old token in the portal so it cannot be reused.
REST API tokens under Settings → REST API tokens are separate — they do not work in Grafana. See REST API tokens.
Troubleshooting
| Symptom | What to check |
|---|---|
| Dashboards sends you to portal login | Sign in to the portal first; production requires an active portal session for SSO |
| Hosted Grafana shows wrong or empty org | Confirm the correct tenant is selected in the portal before opening Dashboards |
| Cannot create an Influx token (BYOG) | Base plan with history retention; Grafana / Influx integration add-on enabled |
| Save & test fails (BYOG) | URL, org, token, and bucket match the dialog exactly; HTTPS URL reachable from your Grafana host |
| Query returns empty | Data in range; correct bucket name; devices publishing on allowed topics |
| Wrong bucket in Explore | Set Default bucket on the data source or use from(bucket: "…") explicitly |
For programmatic CSV/JSON history export, use the History REST API with a REST API token — not Influx/Grafana.
Influx organization
Each account gets a dedicated InfluxDB organization when history is first provisioned. The name is shown in the token dialog (format mqtt-…, derived from your account UUID). That is your Influx namespace — not the shared platform ops org and not a substitute for your account UUID in Flux filters.
Your data is isolated by:
| Layer | What it does |
|---|---|
| Influx org + bucket | Your history namespace (mqtt-… + b_…) |
| Read token (BYOG) | Can read only your bucket in your org |
account_id tag |
On every stored point (use in Flux for defense in depth) |
Copy Organization, Bucket, URL, and Token exactly from the portal dialog into your own Grafana. The wrong org name causes Save & test or Flux queries to fail even with a valid token.
Accounts provisioned before per-tenant orgs may still show the platform org name (isr) until history is reprovisioned.
Hosted Grafana uses the same Influx org and bucket via the provisioned MQTT History datasource — you do not enter these values manually when using Dashboards from the portal.