Grafana Integration

MokoWaaS integrates with a Grafana monitoring stack hosted at bench.mokoconsulting.tech. The integration is automatic: on install or update, the plugin sends a heartbeat that provisions a Grafana datasource for the site.

Architecture

MokoWaaS Plugin (Joomla)
    |
    | POST /api/waas-heartbeat/register
    v
Heartbeat Receiver (bench.mokoconsulting.tech)
    |
    |-- Writes Grafana Infinity datasource YAML
    |-- Restarts Grafana to pick up new datasource
    |-- Sends ntfy notification (mokowaas-heartbeat topic)
    v
Grafana Dashboard
    |
    | GET /?mokowaas=health (per site, on schedule)
    v
Health JSON from each registered site

Heartbeat Registration

When It Fires

The heartbeat is sent automatically during:

Plugin installation (postflight with type install)
Plugin update (postflight with type update)
Package installation (via Pkg_MokowaasInstallerScript::sendHeartbeat())

Payload

The plugin sends a POST request to https://bench.mokoconsulting.tech/api/waas-heartbeat/register with:

{
  "site_url": "https://example.com",
  "site_name": "Example Site",
  "health_token": "<health_api_token>",
  "action": "register"
}

Authentication uses a shared secret sent in the X-MokoWaaS-Key header.

What the Receiver Does

On receiving a registration request, the heartbeat receiver:

Validates the X-MokoWaaS-Key header
Generates a unique datasource UID from the site URL
Writes a Grafana Infinity datasource YAML file to the Grafana provisioning directory
Restarts Grafana to load the new datasource
Sends an ntfy notification to the mokowaas-heartbeat topic with registration details

The datasource YAML configures a Grafana Infinity datasource that polls /?mokowaas=health on the registered site using the provided Bearer token.

Response

On success (HTTP 200):

{
  "status": "ok",
  "ds_uid": "mokowaas-example-com"
}

The ds_uid is logged in the Joomla admin message queue for reference.

Grafana Dashboard

The MokoWaaS Grafana dashboard is organized into 9 rows covering all health metrics:

Row	Panels
1. Overview	Overall status, uptime, plugin version, Joomla version
2. Database	Connectivity, latency, driver, user count
3. Filesystem	Disk space, writable directories, site size
4. Extensions	Extension counts by type, pending updates
5. Backup	Last backup status, age, Akeeba health
6. Security	Admin Tools WAF, SSL certificate, blocked requests
7. Content	Article counts, categories, user activity
8. Infrastructure	Cache status, mail config, scheduled tasks, error log
9. Configuration	SEO settings, template info, config drift

Each row contains panels that query the site's Infinity datasource using JSONPath expressions to extract values from the health check response.

ntfy Notifications

Registration events trigger a notification to the mokowaas-heartbeat ntfy topic. Notifications include:

Site URL
Site name
Registration action (new or update)
Datasource UID

Subscribe to notifications at https://ntfy.sh/mokowaas-heartbeat or use the ntfy app.

Troubleshooting

Heartbeat failed: connection error

The receiver at bench.mokoconsulting.tech may be unreachable. Check:

DNS resolution for bench.mokoconsulting.tech
Outbound HTTPS connectivity from the Joomla server
Firewall rules allowing outbound port 443

Heartbeat failures are logged as warnings in Joomla's log and displayed in the admin message queue. They do not block plugin installation.

Datasource not appearing in Grafana

Verify the heartbeat completed successfully (check Joomla admin messages after install)
Check the Grafana provisioning directory on bench.mokoconsulting.tech
Ensure Grafana was restarted after provisioning
Verify the health endpoint is accessible from the Grafana server

Health data not loading in dashboard

Confirm the health_api_token matches between the plugin configuration and the Grafana datasource
Test the health endpoint directly: curl -sk -H "Authorization: Bearer <token>" "https://example.com/?mokowaas=health"
Check for SSL certificate issues between the Grafana server and the monitored site