{"id":19591920,"url":"https://github.com/catalyst/moodle-tool_heartbeat","last_synced_at":"2025-04-27T14:33:32.208Z","repository":{"id":23479082,"uuid":"26844003","full_name":"catalyst/moodle-tool_heartbeat","owner":"catalyst","description":"Moodle health checks for load balancers / nagios","archived":false,"fork":false,"pushed_at":"2025-04-14T05:33:09.000Z","size":317,"stargazers_count":25,"open_issues_count":22,"forks_count":30,"subscribers_count":28,"default_branch":"MOODLE_39_STABLE","last_synced_at":"2025-04-14T06:32:03.290Z","etag":null,"topics":["cli","cron","heartbeat","icinga","icinga-plugin","moodle-plugin","nagios","nagios-plugin"],"latest_commit_sha":null,"homepage":"https://moodle.org/plugins/tool_heartbeat","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/catalyst.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-11-19T04:13:42.000Z","updated_at":"2025-04-14T05:33:11.000Z","dependencies_parsed_at":"2023-11-07T03:42:53.473Z","dependency_job_id":"72f8860a-1cb3-47d1-8af3-8c67419844d1","html_url":"https://github.com/catalyst/moodle-tool_heartbeat","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catalyst%2Fmoodle-tool_heartbeat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catalyst%2Fmoodle-tool_heartbeat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catalyst%2Fmoodle-tool_heartbeat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catalyst%2Fmoodle-tool_heartbeat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/catalyst","download_url":"https://codeload.github.com/catalyst/moodle-tool_heartbeat/tar.gz/refs/heads/MOODLE_39_STABLE","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251154626,"owners_count":21544531,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cron","heartbeat","icinga","icinga-plugin","moodle-plugin","nagios","nagios-plugin"],"created_at":"2024-11-11T08:31:54.331Z","updated_at":"2025-04-27T14:33:32.197Z","avatar_url":"https://github.com/catalyst.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![ci](https://github.com/catalyst/moodle-tool_heartbeat/actions/workflows/ci.yml/badge.svg?branch=MOODLE_39_STABLE)](https://github.com/catalyst/moodle-tool_heartbeat/actions/workflows/ci.yml?branch=MOODLE_39_STABLE)\n\n# A heartbeat test page for Moodle\n\n- [A heartbeat test page for Moodle](#a-heartbeat-test-page-for-moodle)\n- [Branches](#branches)\n- [What is this?](#what-is-this)\n  - [Front end health](#front-end-health)\n  - [Application health](#application-health)\n  - [Failed login detection](#failed-login-detection)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Testing](#testing)\n\n# What is this?\n\nThis plugin exposes various endpoints that can be wired to load balancers and monitoring systems to help expose when things go wrong.\n\nNOTE: In an ideal world this plugin should be redundant and most of it's functionality built into core as a new API, enabling each plugin to delare it's own extra health checks. See:\n\nhttps://tracker.moodle.org/browse/MDL-47271\n\n# Branches\n\n| Branch             | Moodle version    | PHP Version |\n| ------------------ | ----------------- | ----------- |\n| master             | Moodle 2.7 - 4.1  | Php 5.4.4+  |\n| MOODLE_39_STABLE   | Moodle 3.9 +      | Php 7.2+    |\n\nThe master branch retains very deep support for old Totara's and Moodle's back to Moodle 2.7.\n\nFor any site using Moodle 3.9 or later, it is recommended to use the MOODLE_39_STABLE branch.\n\nThe MOODLE_39_STABLE branch uses the [Check API](https://moodledev.io/docs/apis/subsystems/check) exclusively, which simplifies the code massively.\n\n## Versioning\n\nVersioning follows the [Moodle versioning guidelines](https://moodledev.io/docs/apis/commonfiles/version.php#version)\n\nWhenever a version change is required:\n- The `master` branch should always be `20231024xx` where `xx` increases by 1 each time.\n- The `MOODLE_39_STABLE` branch should always be updated to the current date.\n\n## Front end health\n\nThis is the ```index.php``` check, and is designed to only assert that the front end is healthy and was intended for use as a load balancer test.\n\neg it might chech the *connection* to the filesystem, but not stress too much about the health of the filesystem itself. The reason for this is that front end health checks that fail for the wrong reasons pull nodes from the load balancer for no reason.\n\nhttp://moodle.example.com/admin/tool/heartbeat/\n\nIt will return a page with either a 200 or 503 response code and if it fails a string for why.\n\nBy default it only performs a light check, in particular it does not check the moodle database. To do a full check add this query param:\n\nhttp://moodle.example.com/admin/tool/heartbeat/?fullcheck\n\nThis check can also be run as a CLI:\n\n```\nphp index.php fullcheck\n```\n\n**Example return values for heartbeat**\n\nExample for when the server is healthy.\n```\n(HTTP 200)\nServer is ALIVE\nsitedata OK\n```\n\nExample for when the server is in command line maintenace mode.\n```\n(HTTP 200)\nServer is in MAINTENANCE\nsitedata OK\n```\n\nExample for when the server is not healthy.\n```\n(HTTP 503)\nServer is DOWN\nFailed: database error\n```\n\n\n\n## Application health\n\nNamed `croncheck.php` for compatibility with older versions of this plugin, this page executes all `status` check API checks, and shows any that return non-ok results.\n\nIt is a nagios compliant checker to see if cron or any individual tasks are failing, with configurable thresholds\n\nThis script can be either run from the web:\n\nhttp://moodle.example.com/admin/tool/heartbeat/croncheck.php\n\nOr can be run as a CLI in which case it will return in the format expected by Nagios:\n\n```\nsudo -u www-data php /var/www/moodle/admin/tool/heartbeat/croncheck.php\n```\n\n## Failed login detection\n\nThe script loginchecker is a nagios compliant checker to monitor the number of failed login attempts on a Moodle site as a security intrusion detection mechanic, with configurable thresholds.\n\nThis script can be either run from the web:\n\nhttp://moodle.example.com/admin/tool/heartbeat/loginchecker.php\n\nOr can be run as a CLI in which case it will return in the format expected by Nagios:\n\n```\nsudo -u www-data php /var/www/moodle/admin/tool/heartbeat/loginchecker.php\n```\n\nThe various thresholds can be configured with query params or cli args see this for details:\n\n```\nphp loginchecker.php -h\n```\n\n\n# Installation\n\nBest to always use the latest version from this git repo:\n\nhttps://github.com/catalyst/moodle-tool_heartbeat\n\n\nOr via the Moodle plugin directory (which may be out of date)\n\nhttps://moodle.org/plugins/view/tool_heartbeat\n\n\n# Configuration\n\nhttp://moodle.local/admin/settings.php?section=tool_heartbeat\n\n* Set a fake warning state of 'error' or 'warn'\n* By default in a new install this is set to 'error'. This is done intertionally so that you know your monitoring is wired up correctly end to end. You should see you monitoring raise an alert which tells you that it is a test and links to the admin setting to turn it into normal monitoring mode.\n* Optionaly lock down the endpoints by IP\n\n## Check maximum alerting level configuration\nThis plugin allows configuring maximum permitted alerting level of tasks in the config.php\n\nThis is supplied as list of regex tests and their associated configuration array.\n\nThe configuration is stored in the site config.php under the config setting $CFG-\u003etool_heartbeat_check_defaults\n\nThis should be an array with a form like the following\n```php\n$CFG-\u003etool_heartbeat_check_defaults = [\n    '.+_task_.+' =\u003e [\n        'maxwarninglevel' =\u003e 'info',\n    ],\n    'core_task_tag_cron_task' =\u003e [\n        'maxwarninglevel' =\u003e 'critical',\n    ],\n    'tool_task_.*' =\u003e [\n        'maxwarninglevel' =\u003e 'critical',\n    ],\n];\n```\n\nEach item is tested via `preg_match` against the globally unique check reference string for the check, if it matches, the max warning level configuration is applied, this applies each item in the array from first to last, so if a check matches more than once, the value that is latest in the array is used, this allows setting more broad defaults and then increasing specificity for specific checks to allow them to override the broader defaults.\n\n\n\n# Testing\n\nWhen you first setup this plugin and have wired it end to end with Nagios / Icinga or another monitoring tool, you want the peace of mind to know that it is all correctly working. There is a setting which allows you to send a fake warning so you can confirm your pager will go off. This setting is set to 'error' by default by design\n\nhttp://moodle.local/admin/settings.php?section=tool_heartbeat\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatalyst%2Fmoodle-tool_heartbeat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcatalyst%2Fmoodle-tool_heartbeat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatalyst%2Fmoodle-tool_heartbeat/lists"}