README

Vigilant Drupal Healthchecks

A package that adds healthchecks to any Drupal application and integrates seamlessly with Vigilant.

Installation

Install the module with Composer:

composer require govigilant/drupal-healthchecks

Enable the module via the Drupal UI or with Drush:

drush en vigilant_healthchecks -y && drush cr

Configure the bearer token and thresholds at Configuration → System → Vigilant Healthchecks once the module is enabled.

Usage

Accessing the health endpoint

After configuring a bearer token, the health payload is available at:

POST /vigilant/health

Example curl request:

curl -X POST "https://your-drupal-site.test/vigilant/health" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

Available Checks

Check	Description
DatabaseCheck	Executes a lightweight query to confirm the default database connection responds.
CacheCheck	Writes and reads a payload using the cache backend to ensure it can store, retrieve, and delete items.
QueueCheck	Pushes a probe job through Drupal's queue backend to verify processing behavior and report backlog snapshots.
CronCheck	Ensures Drupal cron has executed within the configurable threshold stored in `vigilant_healthchecks.settings`.
SecurityUpdatesCheck	Uses the Update Manager data to flag projects with outstanding security advisories.

Available Metrics

Metric	Description
CacheEfficiencyMetric	Aggregates hit/miss ratios for the cache bins listed in `vigilant_healthchecks.settings`.
ErrorLogMetric	Counts watchdog error entries recorded within the configurable rolling window.

Extending

You can register your own health checks or metrics by tagging services with vigilant_healthchecks.check or vigilant_healthchecks.metric.

Create a class that extends Vigilant\HealthChecksBase\Checks\Check (or Metric) and implement run()/measure() plus available().
Define the service in MODULE.services.yml and add the appropriate tag.
Inject any dependencies as usual; the HealthCheckRegistry automatically discovers tagged services.

services:
  my_module.check.custom_backend:
    class: Drupal\my_module\Checks\CustomBackendCheck
    arguments:
      - '@my.service'
    tags:
      - { name: vigilant_healthchecks.check }

Development Environment

A ready-to-use Docker Compose setup lives in devenv/. Start the stack: docker compose -f devenv/docker-compose.yml up --build.

This provisions Drupal 11 with MariaDB, installs this module automatically, and exposes the site on http://localhost:8000. The default admin credentials are admin / secret and the bearer token is preset to testing.

Stop everything with docker compose -f devenv/docker-compose.yml down -v when you're done.

Quality

Run the quality checks locally:

composer quality

govigilant / drupal-healthchecks

Maintainers

Details