# Grafana Integration

MokoSuiteClient 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

```
MokoSuiteClient 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 (mokosuiteclient-heartbeat topic)
    v
Grafana Dashboard
    |
    | GET /?mokosuiteclient=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_MokosuiteInstallerScript::sendHeartbeat()`)

### Payload

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

```json
{
  "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-MokoSuiteClient-Key` header.

### What the Receiver Does

On receiving a registration request, the heartbeat receiver:

1. Validates the `X-MokoSuiteClient-Key` header
2. Generates a unique datasource UID from the site URL
3. Writes a Grafana Infinity datasource YAML file to the Grafana provisioning directory
4. Restarts Grafana to load the new datasource
5. Sends an ntfy notification to the `mokosuiteclient-heartbeat` topic with registration details

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

### Response

On success (HTTP 200):

```json
{
  "status": "ok",
  "ds_uid": "mokosuiteclient-example-com"
}
```

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

## Grafana Dashboard

The MokoSuiteClient 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 `mokosuiteclient-heartbeat` ntfy topic. Notifications include:

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

Subscribe to notifications at `https://ntfy.sh/mokosuiteclient-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/?mokosuiteclient=health"`
- Check for SSL certificate issues between the Grafana server and the monitored site