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. NOTE: unknown is generally a bad thing and is semantically treated as an error. It is better to have a result of Unknown until the first result happens, and from then on it is Ok, or perhaps Warning pr Error if the last known result is getting old.	A complex user security report is still running for the first time.
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

Checks are broken down into types, which roughly map to a step life cycle of your Moodle System

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.

(no tracker yet to convert to the Check API)

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

Status checks

/report/status/index.php

A status check is an 'in the moment' test and covers operational tests such as 'can moodle connect to ldap'. The main core status checks are that cron is running regularly and there has been no failed tasks.

An additional status 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 'OK' requires some sort of threshold, eg network response within 500ms, then that threshold should be managed by the plugin and optionally exposed as a admin setting. The plugin may choose to have different thresholds for Warning / Error / Critical.

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

Performance checks

/report/performance/index.php

Each check might simply check for certain settings which are known to slow things down, or it might actually do some sort of test like multiple reads and writes to the db or filesystem to get a performance metric.

(no tracker yet to convert to the Check API)

Health checks

/admin/tool/health/

The 'health center' is currently unsupported and contains some very old code. It is conceptually similar to 'status' checks except larger more long terms issues, such as detecting corrupt records. It may be improved and converted to the Check API or it may be completely deprecated.

(no tracker yet to convert to the Check API)

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->name = get_string('check_foobar_name', mod_myplugin');
       $url = new \moodle_url('/mod/myplugin/info.php');
       $this->actionlink = new \action_link($url, get_string('checkinfo', 'mod_myplugin'));
   }

   public function get_result() : result {
       if (some_check()) {
           $status = result::ERROR;
           $summary = get_string('check_foobar_error', 'mod_myplugin');
       } else {
           $status = result::OK;
           $summary = get_string('check_foobar_ok', 'mod_myplugin');
       }
       $details = get_string('check_details', 'mod_myplugin');
       return new result($status, $summary, $details);
   }

}

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->component = 'mod_myplugin';
       $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 lookup.
       $this->details = 'expensive details!';
   }

}