Check API

Moodle 3.9

Checks

WARNING: Work in Progress

https://tracker.moodle.org/browse/MDL-67818

A Check is a runtime test to make sure something is working well. Checks can be used for a variety of purposes including:

• configuration checks
• security checks
• performance checks
• health checks

Moodle has had various types of checks and reports for a long time but they were inconsistent and not machine readable. 3.9 they were unified under a single Check API which also enabled plugins to cleanly define their own additional checks.

Having these centralized and with a consistent contract makes it much easier to ensure the whole system is running smoothly.

Result state of a check

Status	Meaning	Example
N/A	This check doesn't apply - but we may still want to expose the check	secure cookies setting is disabled because site is not https
Ok	A component is configured, working and fast.	ldap can bind and return value with low latency
Info	A component is OK, and we may want to alert the admin to something non urgent such as a deprecation, or something which needs to be checked manually.
Unknown	We don't yet know the state. eg it may be very expensive so it is run using the Task API and we are waiting for the answer.	A complex user security report is still running
Warning	Something is not ideal and should be addressed, eg usability or the speed of the site may be affected, but it may self heal (eg a load spike)	auth_ldap could bind but was slower than normal
Error	Something is wrong with a component and a feature is not working	auth_ldap could not connect, so users cannot start new sessions
Critical	An error which is affecting everyone in a major way	Cannot read sitedata or the database, the whole site is down

How the various states are then leveraged is a local decision. A typical policy might be that health checks with a status of 'Error' or 'Critical' will page a system administrator 24/7, while 'Warning' only pages during business hours.

Check types and reports

Install and configuration checks

/admin/index.php?cache=1

/admin/environment.php

These are environmental checks to make sure a Moodle instance is fully setup.

Security checks

These are checks to make sure a Moodle instance is hardened correctly for you needs.

/report/security/index.php

https://tracker.moodle.org/browse/MDL-67776

Performance checks

/report/performance/index.php

Each check might exercise

Health checks

/report/status/index.php

A Health check covers operational tests such as 'can moodle connect to ldap'. The main core health check is to ensure that cron is running regularly and there has been no failed tasks.

An additional health check is likely the most common type of check a plugin would define. Especially a plugin that connects to a 3rd party service. If the concept of 'healthy' requires some sort of threshold, eg network response within 500ms, then that threshold should be managed by the plugin and ideally exposed as an editable admin setting. The plugin may choose to have different thresholds for Warning / Error / Critical.

https://tracker.moodle.org/browse/MDL-47271

Implementing a new check

A check class

And make a new check class in mod/myplugin/classes/check/foobar.php

<?php namespace mod_myplugin\check; use core\check\check;

class foobar extends check {

   public function __construct() {
       $this->id = 'foobar';
       $this->component = 'mod_myplugin';
       $this->name = 'my foobar check';
       $this->details = 'some details!';
       $this->status = check::ERROR;
       $this->summary = 'foobar summary';
   }

}

lib.php callback

Decide on what type of check, ie what report it should be included into. Some checks might make sense to be reused with more than one report, eg both Performance and Health.

Implement a the right callback in lib.php for the report you want to add to, and return an array (usually with only 1 item) of check objects:

/mod/myplugin/lib.php

function mod_myplugin_security_checks() {

   return [new mod_myplugin\check\foobar()];

}

Multiple instances of checks

Checks have been designed to be dynamic so you can return different checks depending on configuration, so auth_ldap would not return a check if the plugin is not enabled. Hypothetically if auth_ldap could be configured with 5 ldap servers then you could return 5 independent checks for each remote connection, each with different labels and information.

If you plan to return multiple instances of a check class, make sure that each instance has a unique id.

function mod_myplugin_security_checks() {

   return [
       new mod_myplugin\check\foobar('one'),
       new mod_myplugin\check\foobar('two'),
   ];

}

Set the internal id in a way which is unique across your components namespace:

<?php namespace mod_myplugin\check; use core\check\check;

class foobar extends check {

   public function __construct($id) {
       $this->id = 'foobar' . $id;
       $this->component = 'mod_myplugin';
       $this->name = 'my foobar check for ' . $id;
       ....
   }

}

Performance and check details

Checks can provide details on a check, such as the complete list of bad records. Generally this type of information might be expensive to produce so you can defer this lookup until get_details() is called specifically rather than setting this in the constructor.

<?php namespace mod_myplugin\check; use core\check\check;

class foobar extends check {

   public function __construct() {
       $this->id = 'foobar';
       $this->name = 'my foobar check';
       $this->details = 'some details!';
       $this->status = check::ERROR;
       $this->summary = 'foobar summary';
   }
   public function get_details() : string {
       // Some really expensive lookip.
       $this->details = 'expensive details!';
   }

}