Skip to main content

Use your own Grafana

The dashboards in the monitoring bundle need Grafana 10 or later, and are tested on the Grafana version the bundle ships (13.1). They find their data through a datasource variable, so they attach to whichever PostgreSQL datasource you choose. You still need the Hop side and a logging database: see Use your own PostgreSQL for those.

Import through the Grafana UI​

  1. Add a PostgreSQL datasource for the logging database: Connections → Data sources → Add data source → PostgreSQL. Any name works. Use a database user that can only read the logging tables, never the one Hop writes with: anyone who can open a dashboard can send the datasource a query of their own. sql/grafana-reader.sql creates such a user (see Use your own PostgreSQL).
  2. Import the two dashboards: Dashboards → New → Import → Upload dashboard JSON file, once for grafana/dashboards/putki-monitoring.json and once for grafana/dashboards/putki-log-detail.json. Select your datasource when asked.

Import both. Clicking a run on the monitoring dashboard opens the log detail dashboard by its identifier, so the link breaks if only one is imported.

Provision from files​

If you manage Grafana as code, copy the dashboards and a provider definition:

mkdir -p /var/lib/grafana/dashboards/putki
cp grafana/dashboards/*.json         /var/lib/grafana/dashboards/putki/
cp grafana/dashboards/dashboards.yml /etc/grafana/provisioning/dashboards/putki.yml

Edit path in putki.yml to /var/lib/grafana/dashboards/putki.

grafana/datasources/datasources.yml is a working datasource definition. It reads its values from environment variables (LOGGING_DB_HOST, _PORT, _NAME, _USER, _PASSWORD, _SSLMODE), where _USER and _PASSWORD are the read-only user's. Set all six: Grafana's provisioning understands $VAR and ${VAR} but not ${VAR:-default}, and an unset variable silently becomes an empty value.

Alerts​

The alert rules are written by the bundle's Grafana when it starts, so they are not part of the JSON files. To get the same rules into your Grafana as provisioning files, generate them once from the bundle folder:

sh bin/putki-alerting.sh /tmp/putki
cp /tmp/putki/alerting/putki-rules.yaml /etc/grafana/provisioning/alerting/

The rules read the datasource with the UID postgres: give your logging datasource that UID, or change datasourceUid in the file. The same PUTKI_ALERT_* settings as in Get alerts tune them when set in the shell that runs the script. putki-contact-points.yaml is only needed if you want Putki's Slack and Google Chat contact point; most Grafanas already route alerts somewhere.

Keep your changes​

Provisioned dashboards are reset to the shipped version whenever Grafana restarts. To customise one, save a copy under a new name (Save as) and edit the copy.