Check API
Moodle 3.9
Checks
WARNING: Work in Progress
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 for a long time and in 3.9 they were unified under a single Check API enabling plugins to cleanly define their own additional checks.
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 leverages is a local decision. A typical policy might be Error and Critical will page a system administrator 24/7, but Warning only page 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
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.
Implementing a new check
First 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 check objects:
function auth_ldap_status_checks() {
return [
new auth_ldap\check\connect(),
];
}
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.
