Learn how to monitor the health of your server using an easy framework.
Server health monitoring allows you to keep an eye on your server at all times. To define what aspects of your server health you want to monitor, you have to create a health endpoint. In this article, we explain how to create a server health endpoint using the Semonto framework.
To get started quickly, a server health endpoint written in PHP is available. This framework reveals the health condition of the server for external monitoring. Read more about server health monitoring in this guide.
You can find the source code on GitHub.
This framework includes default tests for monitoring the used disk space, the memory usage, the server load and if a connection to a MySQL database can be made. And the framework can be easily extended with your own custom tests for your server.
This framework is tested with PHP 7.4 and higher.
You need to copy or clone all the files from the repository to an endpoint on your server. Typical endpoints are https://yourserver.com/status or https://yourserver.com/health.
In the config directory is an example config file. Rename this config file to config.php. In this config file you can specify how the framework should connect to a MySQL or MariaDB database and which tests should be run and you can set the configuration options for the tests. The function
getConfig() returns all the configuration options.
getConfig() function you can specify which test should run. In the array tests you can add the tests that should run and you can supply some configuration options for each test. Custom tests should also be added to this array in order to run. The configuration options are for example disk space thresholds, memory usage thresholds or which disks should be monitored.
The following config file indicates that a database connection should be made and that following tests must run on every request for the server health status:
$config = [
'db' => [
'connect' => true,
'db_host' => 'https://my-db-server.com',
'db_user' => 'DBUSER',
'db_pass' => 'DBPASS',
'db_port' => '3306',
'tests' => [
'test' => 'ServerLoad',
'config' => [
'type' => 'current',
'warning_threshold' => 5,
'error_threshold' => 15
'test' => 'DiskSpace',
'config' => [
'disks' => [
'name' => '/dev/vda1',
'warning_percentage_threshold' => 75,
'error_percentage_threshold' => 90
'test' => 'MySQLFetchOperation',
'config' => [
'database' => 'semonto_database',
'database_table' => 'test_servers'
'test' => 'NotificationQueueTotal',
'config' => 
'test' => 'NotificationQueueFailed',
'config' => 
'test' => 'NotificationQueueDelayed',
'config' => 
This framework provides the following tests: ServerLoad, DiskSpace, MySQLPing, MySQLFetchOperation and DiskSpace. Note that the MySQL tests also work on MariaDB without any changes.
The server load test has three configuration options. The type which can be
average_15_min. And a warning and error threshold. The default thresholds are 5 for warnings and 15 for errors.
You can register multiple server load tests, for each type only one. And you should adjust the warning and error thresholds to the amount of CPUs your server has available. Check this guide for more information on system load.
You can specify multiple disks for this test and for each disk you can specify the warning and error threshold percentages individually. These thresholds have 75% and 90% as defaults. If a disk can’t be found this will result in a warning.
This test pings a MySQL database and measures how long it takes. There is no extra configuration needed except the DB connection settings.
This test tries to fetch a number of rows from a database table. You need to specify the database name and the table.
The memory usage test has config options for the warning and error percentage. The defaults for these percentages are 90% and 95%.
You can easily extend this framework with your own custom test for the server’s application. Some examples of custom tests are:
Each test is performed by its own class which is stored in its own file. Those custom test files should be stored in the custom tests directory
src/ServerHealth/customTests. This is where the framework will look for the files. It is also important that the file name is exactly the same as the name for the test.
For example if you have a test with the name
NotificationQueueFailed, then this should be in the directory
src/ServerHealth/customTests with filename
In the custom test directory is an example file to get started with your custom tests.
A more human-friendly name for each test should be set with the name attribute of your test class.
Each custom test must have a method
performTests(). This method should perform the actual tests. Optional configuration options and the database connection are inherited from the framework and available in the config attribute.
performTest() must always return an instance of
ServerHealthResult, so make sure to handle all possible outcomes for the tests. Class
ServerHealthResult has two required parameters in the constructor. The name of the test, best to use a human-friendly name, and the status. For the status you can use the following values:
ok, warning or error. Or you can use the class
ServerStates with corresponding class constants.
There are two optional parameters: description and value.
The description should be a human friendly string about the test result. For example: 2 min since the last successful run.
The value should be a numeric value. This numerical will be displayed in Semonto if the human friendly text is not available or to draw a chart. For example a percentage or a number of failed items in a queue.
Make sure to register your custom tests in the config file. If all goes well, this endpoint will respond in a JSON format that Semonto can understand.
You can now configure Semonto to start monitoring this endpoint. You can read more about this in this guide. If everything goes well the results should look like the example at the top.
Feel free to contact us if you need any help setting this up.