1. Why Grafana with Zabbix? #
Complementing the Zabbix interface, not replacing it.
Complementarity #
Zabbix remains the reference for collection, triggers and notifications. Grafana brings richer visualizations, variables for a single dashboard covering all hosts, and above all combining sources: Zabbix metrics, Prometheus, Loki or Elasticsearch logs in the same dashboard.
The link is made through Grafana's Zabbix plugin (the alexanderzobnin-zabbix-app app), maintained by Grafana Labs. It provides a data source, a problems panel and example dashboards.
Who does what #
| Need | Zabbix interface | Grafana |
|---|---|---|
| Configure collection and triggers | Yes | No |
| Notify, escalate, acknowledge | Yes | Acknowledgment possible from the problems panel |
| Per-host or per-template dashboards | Yes | Yes, with variables |
| Mix Zabbix with other sources | No | Yes |
| Dashboards for teams without a Zabbix account | No | Yes, with Grafana permissions |
2. Preparing Zabbix #
A dedicated, read-only account.
User and token #
- Create a
Grafanauser group with read permission on the host groups to expose. - Create a
grafanauser in this group, with the User role (API access must be allowed by the role). Users > API tokens > Create API token: a token for thegrafanauser, with an expiration date.
Common mistake: Never use the Admin account for Grafana: all Grafana users would then see the entire fleet, and a password leak would give control of Zabbix.Good to know: The grafana user's Zabbix permissions delimit what Grafana can display. To isolate teams, create one data source per team, each with its own Zabbix user.3. Installing the plugin and configuring the data source #
Through the interface or with provisioning.
Installation #
# Installation classique
grafana-cli plugins install alexanderzobnin-zabbix-app
systemctl restart grafana-server
# Avec Docker
docker run -d -p 3000:3000 -e GF_INSTALL_PLUGINS=alexanderzobnin-zabbix-app grafana/grafana:latestThen enable the app: Administration > Plugins and data > Plugins > Zabbix > Enable. The Zabbix data source becomes available in Connections > Data sources.
Data source settings #
| Field | Recommended value | Role |
|---|---|---|
| URL | http://zabbix-web:8080/api_jsonrpc.php | API endpoint (the interface URL followed by api_jsonrpc.php) |
| Auth type | API token | Safer than a password; revocable in Zabbix |
| Trends | Enabled, after 7d, range 4d | Uses hourly trends for long periods |
| Cache TTL | 1h | Cache of group, host and item lists |
| Direct DB connection | Optional | Reads history and trends directly from the database via a MySQL or PostgreSQL data source |
Provisioning #
For a reproducible deployment, declare the app and the data source in /etc/grafana/provisioning/:
# provisioning/plugins/zabbix.yaml
apiVersion: 1
apps:
- type: alexanderzobnin-zabbix-app
disabled: false
---
# provisioning/datasources/zabbix.yaml
apiVersion: 1
datasources:
- name: Zabbix
type: alexanderzobnin-zabbix-datasource
uid: zabbix
access: proxy
url: http://zabbix-web:8080/api_jsonrpc.php
jsonData:
authType: token
trends: true
trendsFrom: 7d
trendsRange: 4d
cacheTTL: 1h
secureJsonData:
apiToken: ${ZABBIX_API_TOKEN}Good practice: The token comes from an environment variable (or a secrets manager), never from the versioned file. After startup, the data source's Save & test button should show the Zabbix API version.
4. Writing queries #
Group, host, tag, item, functions.
The query editor #
With the Metrics query type, each field filters the next one. A field accepts an exact name or a regular expression between slashes: /^web-\d+$/ selects web-01, web-02...
| Query type | Usage |
|---|---|
| Metrics | Numeric series (CPU, memory, traffic) |
| Text | Text values (version, state) for Stat or Table panels |
| Problems | Current or past problems, for the problems panel or a table |
| Item ID | Items designated directly by their identifier |
| Services / SLA | Availability of Zabbix services |
Functions #
Functions transform series before display, in the style of Graphite:
| Function | Example | Effect |
|---|---|---|
| groupBy | groupBy(5m, avg) | Aggregates each series per interval |
| aggregateBy / sumSeries | sumSeries() | Merges several series into one (total traffic of a group) |
| top / bottom | top(5, avg) | Keeps the 5 highest series |
| rate / delta | rate() | Turns a counter into a rate |
| scale | scale(8) | Converts bytes into bits |
| setAlias / replaceAlias | setAlias($__zbx_host_name) | Renames series in the legend |
| timeShift | timeShift(7d) | Compares with the previous week |
5. One dashboard for all hosts #
Variables and the problems panel.
Variables #
In Dashboard settings > Variables, create Query variables on the Zabbix data source:
| Variable | Query type | Parameters |
|---|---|---|
group | Group | Group: /.*/ |
host | Host | Group: $group, Host: /.*/; multi-value and Include All |
In queries, use $group and $host: a multiple selection is automatically turned into a regular expression. The same dashboard then serves the whole fleet.
The problems panel #
The plugin adds the Zabbix Problems panel: list of problems with severity, duration, tags and acknowledgments, filterable by group, host, minimum severity and tags. Depending on the Zabbix user's permissions, it allows acknowledging from Grafana.
Good practice: Place the problems panel next to the graphs of the same application: the cause (a Zabbix problem) and the effect (latency, errors in Prometheus or Loki) are visible together.
Example dashboards #
The data source's Dashboards tab offers to import dashboards shipped with the plugin (Zabbix server health, Linux server): a good starting point to adapt.
6. Performance and operations #
Not overloading Zabbix from Grafana.
History or trends #
- Enable trends: beyond the after period, the plugin reads hourly averages instead of raw history.
- Avoid overly broad regular expressions (
/.*/on the item) across thousands of hosts: each panel then makes heavy API calls. - Set panels' Max data points and minimum interval; refreshing every 5 s brings nothing for items collected every minute.
- For very large volumes, the direct connection to the database (preferably a read replica) avoids going through the PHP API.
Alerts #
The plugin also allows Grafana alert rules on Zabbix data. Still, keep infrastructure alerts in Zabbix (triggers, dependencies, escalations): two systems alerting on the same data produce duplicates.
Troubleshooting #
| Symptom | Likely cause | Fix |
|---|---|---|
| Not authorised during the test | Expired token or role without API access | Recreate the token; check the user's role |
| Empty host lists | No read permission on the groups | Add the host groups to the Grafana user group |
| New hosts missing from lists | Data source cache | Wait for the Cache TTL to expire or reduce it |
| Slow graphs over 30 days | Reading raw history | Enable trends or the direct connection |
| Plugin not found after installation | App not enabled or Grafana not restarted | Enable the Zabbix app and restart |
7. Best practices #
Checklist.
Checklist #
- A dedicated, read-only Zabbix user with an expiring API token; never the Admin account.
- Data source and app provisioned in YAML, token injected through an environment variable.
- Trends enabled, one-hour Cache TTL, targeted regular expressions.
groupandhostvariables for one dashboard per server type rather than one per server.- Infrastructure alerts stay in Zabbix; Grafana is used to visualize and correlate.
- Grafana dashboards exported as JSON and versioned, like Zabbix templates.
