=== Vigil Health & Cron Monitor ===
Contributors: puzaricloud
Tags: health check, monitoring, cron, uptime, site health
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Health check endpoint, Site Health tests and a dashboard widget: database, WP-Cron, updates, PHP, disk and more. No account needed.

== Description ==

Vigil Health & Cron Monitor answers one question for you and for your monitoring tool: is this WordPress site healthy right now, and if not, what exactly is wrong?

It works on its own. You do not need an account anywhere.

**What you get for free**

* **A health endpoint** at `/wp-json/vigil-health/v1/health`, protected by a secret generated when you activate the plugin. It returns JSON in the Oh Dear health check format (`finishedAt`, `checkResults[]` with `name`, `label`, `status` ok / warning / failed, `notificationMessage`, `shortSummary`, `meta`), so Oh Dear, Vigil, or any tool that can check a JSON field can poll it. The endpoint answers HTTP 200 whenever the secret is right; each check carries its own status.
* **Site Health tests** under Tools > Site Health for every check below.
* **A dashboard widget** that summarises the checks for administrators.

**The checks**

* Database: connectivity and the time of a trivial query (warning from 500 ms, failed from 2 s).
* WP-Cron: whether `DISABLE_WP_CRON` is set, how many scheduled events are overdue and by how long. Overdue by more than an hour means cron is not running.
* Updates: pending WordPress core, plugin and theme updates (read from WordPress' own update data; the plugin never triggers an update check).
* PHP version: against the official PHP end-of-life dates.
* Disk space: free space on the disk that holds your uploads.
* Object cache: if a persistent object cache (Redis, Memcached) is installed, a write and read-back round trip.
* HTTPS and site URL: site address and WordPress address on the same host and on https.
* Debug mode: `WP_DEBUG` (and `WP_DEBUG_DISPLAY`) switched on in a production environment.
* Uploads writable: the uploads directory exists and is writable.

Developers can add or change checks with the `vigil_health_check_results` filter and tune thresholds with `vigil_health_db_warning_ms`, `vigil_health_db_failed_ms` and `vigil_health_cron_grace_seconds`.

**Optional: alerts with Vigil**

If you want to be told when something breaks, you can connect the plugin to Vigil, a monitoring service by PuzariCloud (free plan available), or to your own self-hosted Vigil. Paste an API key in Settings > Vigil Health, tick the consent box, and the plugin:

1. creates an "App health" monitor in Vigil that polls the endpoint above with your secret and alerts per check ("Database is failed"), not just "site down";
2. creates a heartbeat monitor and pings it every hour from WP-Cron, so you are alerted when WP-Cron stops running (the ping goes to `/fail` when a check is failing);
3. shows both monitors' status in the dashboard widget.

Nothing is sent to Vigil unless you connect. Disconnect removes the API key from your site (and can delete the two monitors in Vigil).

= Third-party service =

This plugin can connect to **Vigil**, a service operated by PuzariCloud at [https://puzaricloud.in](https://puzaricloud.in) (or to a self-hosted Vigil at an address you enter). This is optional and off by default. Only after an administrator enters an API key and ticks the consent checkbox, the plugin sends:

* to `https://puzaricloud.in/api/v1/...` (or your own address): the API key, the URL of this site's health endpoint and its secret, and the site's host name (used to name the monitors); and requests for the status of the two monitors when an administrator views the dashboard or the settings page;
* to `https://puzaricloud.in/ping/...`, once an hour from WP-Cron: the name, status and one-line summary of each health check.

Vigil then requests your health endpoint at the interval of your plan. No posts, users, visitor data or other personal data are sent.

* Terms of service: [https://puzaricloud.in/terms](https://puzaricloud.in/terms)
* Privacy policy: [https://puzaricloud.in/privacy](https://puzaricloud.in/privacy)

== Installation ==

1. Install the plugin from Plugins > Add New, or upload the `vigil-health` folder to `/wp-content/plugins/`.
2. Activate it. A secret is generated; nothing is sent anywhere.
3. Open Settings > Vigil Health to see the checks, the endpoint URL and the secret.
4. Point your monitoring tool at the endpoint, sending the secret in the `vigil-health-secret` header:
   `curl -H "vigil-health-secret: YOUR_SECRET" https://example.com/wp-json/vigil-health/v1/health`
5. Optional: paste a Vigil API key under "Alerts with Vigil" and tick the consent box to get alerts.

== Frequently Asked Questions ==

= Do I need a Vigil account? =

No. The endpoint, the Site Health tests and the dashboard widget work without any account. Connecting to Vigil is optional and only adds alerting.

= Which monitoring tools can read the endpoint? =

Any tool that understands the Oh Dear application health format, including Oh Dear and Vigil. Tools that can only check a JSON field can check the top-level `status` field (`ok`, `warning` or `failed`).

= How is the endpoint protected? =

With a 40-character random secret, compared in constant time. Send it in the `vigil-health-secret` header (the `oh-dear-health-check-secret` header and a `?secret=` query parameter also work). Without the right secret the endpoint answers HTTP 401 and reveals nothing. You can generate a new secret at any time.

= Why does the endpoint return HTTP 200 when a check fails? =

So your monitoring tool can tell "the site answered and the database is slow" apart from "the site is down". Each check carries its own status.

= My site has little traffic. Will the WP-Cron heartbeat raise false alarms? =

WP-Cron only runs when someone visits the site. If your site can go more than 90 minutes without a visit, set up a real cron job that calls `wp-cron.php` (and set `DISABLE_WP_CRON`). That is good practice anyway, and the heartbeat then tells you when that cron job stops.

= Does it work with a self-hosted Vigil? =

Yes. Enter your Vigil address next to the API key.

= What happens on uninstall? =

The secret, the connection settings and the scheduled heartbeat are removed. Monitors in Vigil are kept unless you disconnect with "also delete both monitors in Vigil" first.

== Changelog ==

= 1.0.0 =
* First release: health endpoint (Oh Dear format), nine checks, Site Health tests, dashboard widget, optional Vigil connection with an hourly WP-Cron heartbeat.

== Upgrade Notice ==

= 1.0.0 =
First release.
