Grafana

Zet Grafana-waarschuwingen om in timeline-sparklines op je Lock Screen. Bekijk de metriekgeschiedenis in één oogopslag met realtime-updates terwijl waarschuwingen actief zijn.

Get Your Integration Key

Open de PushWard-app → Instellingen → Integratiesleutel om je standaard hlk_-sleutel te vinden.

Een aparte sleutel voor deze integratie aanmaken:

1. Ga naar Instellingen → Sleutels beheren
2. Tik op +
3. Stel een naam in (bijv. "Grafana"), kies , Volledig beheer als scope, en beperk totgrafana-*
4. Kopieer de gegenereerde hlk_-sleutel

Grafana App Plugin (Recommended)

The PushWard app plugin is the in-Grafana setup and management layer. One click wires up the webhook contact point, validates your key, and renders the live timeline sparkline inside Grafana using your existing datasource — no separate container and no extra Prometheus config. It can also poll PromQL on a schedule and publish the results as iOS Home and Lock Screen widgets, so it fully replaces the standalone container described further down.

Requirements

• Grafana 12.3 or newer (unified alerting plus app-plugin IAM service accounts)
• A PushWard integration key (hlk_ prefix) — the notifications capability for test pushes, and widgets to publish widgets
• A Prometheus or VictoriaMetrics datasource in Grafana (for the timeline history)

1. Install the Plugin

Self-hosted today: download the release ZIP from the plugin repository, unzip it into your Grafana plugins/ directory, and allowlist the unsigned plugin:

[plugins]
allow_loading_unsigned_plugins = pushward-alerts-app

Restart Grafana, then enable the app under Administration > Plugins > PushWard and open its Configuration page.

2. Connect

On the Connect page, one click creates the PushWard webhook contact point (no manual URL or header copying) along with a scoped Grafana service-account token, and validates your integration key against the PushWard API. Add that contact point to any alert rule's notification policy to start receiving timelines.

3. Configure

On the Configuration page (Admin only) you set:

• Integration key — your hlk_ key
• Datasource — the Prometheus/VictoriaMetrics datasource the backend queries for metric history
• Severity mapping — which alert label drives the accent color and icon
• History window and poll interval — how far back to backfill and how often to refresh while firing
• Widgets — the widget definitions described below

Widget Engine

Beyond timelines, the backend can poll PromQL on a schedule and publish the results as iOS widgets. Declare value, progress, status, gauge, and stat_list widgets in the configuration; each runs on its own interval with an on_change or always trigger mode, and a multi-series query fans out into one widget update per series.

Management and Dashboard

The Overview, Activities, and Widgets pages show current Live Activities, a recent delivery log, and your declared widgets, and let you send a test notification or fire a test timeline. Enabling the app also imports a PushWard Delivery dashboard that charts backend metrics — alerts received, activities created, pushes sent, and errors. Alert rules and instances get a View in PushWard action too.

Standalone Container (Legacy)

How It Works

1. Webhook — Grafana fires an alert and sends the webhook to pushward-grafana
2. Query — The service queries Prometheus or VictoriaMetrics for the metric's recent history
3. Timeline — A Live Activity starts with a sparkline chart showing the metric over time
4. Poll — While the alert is firing, the service polls for new data points and pushes updates
5. Resolve — When the alert resolves, the activity ends with a final snapshot

Deploy the Service

services:
  pushward-grafana:
    image: ghcr.io/mac-lucky/pushward-grafana:latest
    ports:
      - "8090:8090"
    environment:
      PUSHWARD_URL: https://api.pushward.app
      PUSHWARD_API_KEY: hlk_YOUR_INTEGRATION_KEY
      PUSHWARD_METRICS_URL: http://prometheus:9090
      # Optional: webhook secret (must match Grafana contact point)
      # PUSHWARD_WEBHOOK_TOKEN: your-shared-secret
      # Optional: Grafana API for auto-extracting PromQL from alert rules
      # PUSHWARD_GRAFANA_URL: http://grafana:3000
      # PUSHWARD_GRAFANA_API_TOKEN: glsa_...
    restart: unless-stopped

Configure the Grafana Contact Point

1. Navigate to Alerts & IRM > Alerting > Contact points
2. Click + Add contact point
3. Select Webhook as the integration type
4. Set URL to your pushward-grafana instance (e.g. http://pushward-grafana:8090/webhook)
5. If you set PUSHWARD_WEBHOOK_TOKEN, expand Optional settings and set Authorization header scheme to Bearer with the matching token
6. Click Test, then Save

Create a Notification policy that routes alerts to this contact point.

Configuration

Dashboard Links

The bridge forwards the alert's silenceURL, generatorURL, and panel links straight through to the notification — both http:// and https:// schemes are accepted, so a self-hosted Grafana on a LAN (e.g. http://grafana.internal/d/abc) round-trips cleanly for users on VPN. URLs without an http(s):// scheme are dropped on the way in.

PromQL Resolution

The timeline needs a PromQL expression to query metric history. The app plugin reads the firing rule's query from your datasource automatically; the standalone container resolves the query in this order:

1. Auto-extract (recommended) — If PUSHWARD_GRAFANA_URL and PUSHWARD_GRAFANA_API_TOKEN are set, the service reads the alert rule's PromQL expression via the Grafana API. No per-rule configuration needed.
2. Annotations — Add annotations to your Grafana alert rules to specify the query explicitly.
3. Webhook values — Falls back to the numeric values included in the Grafana webhook payload (no history, just the current value).

Per-Rule Annotations

Add these annotations to your Grafana alert rules to override the query or tune the sparkline:

Severity Colors

The sparkline accent color and icon are derived from the severity label on the alert rule: