This page will help you to create an healthcheck check. You can then propose your new check to be included in the OBM distribution (supported by the Core Team) or in the contrib section.

General principles of the HealthCheck system

The HealthCheck system consist of a REST API and a web front end. The checks are executed on the obm-ui server (in case of a distributed infrastructure).

Components of the HealthCheck system

The OBM HealthCheck system is a collection of modules. Each module contains an id (that should be unique amongst all modules), a name (that should be human readable), a description (that should also be human readable !), and an optionnal url (more on that later).

Each module contains a number of individual checks. For example, a module "PHP configuration" can have a check for the PHP version, a check for the PHP magic_quote setting, etc...

Layout of the healthcheck system

The healthcheck system is located in /usr/share/obm/www/php/healthcheck on Debian, /usr/share/obm/php/healthcheck on RedHat. The server part (the one that is interesting right now) is in the backend directory. Here are the notable files & directories inside:

• backend/checks

in this directory, there is one directory by module.

• backend/checks/[module id]

This directory contains all checks stuff related to the module [module id], that are:

• backend/checks/[module id]/Module.php

This PHP file contains the module definition for [module id]. The definition is a class implementing the ModuleInterface interface.
The implementation should define the following public attributes:

• id
• name
• description
• url

As the class is implementing ModuleInterface, it should implement the isEnabled method. This method should return TRUE in most cases but is there to actually allow the system to disable a whole module, based on some business rules or environmental conditions.
The system will traverse the backend/checks directory, find all Module.php files and build the list of enabled modules dynamically.

• backend/checks/[module id]/checks.json

The JSON file listing all the checks available for [module id]

• backend/checks/[module id]/[check id].php

The PHP implemantation of the check [check id] of module [module id].

Anatomy of an healthcheck check

An healthcheck check belongs to a module. It is made of two parts:

1. the check definition, in JSON
2. the check implementation, in PHP

The check definition

A check definition should contains the following keys :

The check definition should be appended in the backend/checks/[module id]/checks.json file.

Example of a checks.json file:

{
  "checks": [  
    {  
      "id": "ReadabilityStatus",  
      "name": "Readability Check",  
      "description": "Checks that OBM configuration files are readable on the UI server.",  
      "url": "http://obm.org/wiki/configuration-1",  
      "parentId": null  
    },  
    {  
      "id": "MinimalSubsetStatus",  
      "name": "Minimal Subset Check",  
      "description": "Checks that OBM configuration files contains the minimum required information.",  
      "url": "http://obm.org/wiki/configuration-1",  
      "parentId": null  
    }  
  ]  
}  

The check implementation

The check implementation is as simple as possible ! It's a PHP file, named [check id].php, and located in the backend/checks/[module id]/ directory. It should require_once some files, create a class implementing the Check interface, and return a CheckResult. That's all. Here is a template of a check that never fails :

<?PHP
require_once dirname(__FILE__) . '/../../Check.php';
require_once dirname(__FILE__) . '/../../CheckResult.php';
require_once dirname(__FILE__) . '/../../CheckStatus.php';

class NeverFails implements Check {

  /* the method that should be implemented to respect the Check interface */
  function execute() {
    $result = new CheckResult(CheckStatus::OK);
    return $result;
  }
}

Unfortunately, sometimes checks fail, and you want to tell the user some more informative messages to help him to resolve the issue. Here is an example of a check that always fail :

<?PHP
require_once dirname(__FILE__) . '/../../Check.php';
require_once dirname(__FILE__) . '/../../CheckResult.php';
require_once dirname(__FILE__) . '/../../CheckStatus.php';

class AlwaysFails implements Check {

  /* the method that should be implemented to respect the Check interface */
  function execute() {
    $result = new CheckResult(CheckStatus::ERROR);
    $result->messages = array();
    $result->messages[] = "You are missing some configuration thingy for this to work.";
    $result->messages[] = "You are missing some firewall rules too.";
    return $result;
  }
}

Testing

All checks are unit tested using PHP Unit. See the directory php-tests/healthcheck for examples.