katmore/healthsvc

health webservice

v1.0.3 2018-12-15 03:39 UTC

Requires

• php: >=7.2.1

Requires (Dev)

• guzzlehttp/guzzle: ~6.0
• php-di/phpdoc-reader: ^2.1
• phpunit/php-code-coverage: ^6.0
• phpunit/phpunit: ^7

MIT, GPL-3.0+

• Doug Bird

README

Healthsvc is a system health status service with a RESTful API interface. It can be used stand-alone or be integrated into existing projects. It is intended to be used conjunction with devops workflows, functional testing, monitoring software, etc.

Usage as Standalone Service

• Download healthsvc:

  git clone https://github.com/katmore/healthsvc.git

• Update using Composer:

  cd healthsvc
  composer update

• Print list of available "host-sanity" tests using the host-sanity-config.php command-line utility

  bin/host-sanity-config.php --print-bin-list

• Add a "host-sanity" test with the label "free-space" using the host-sanity-config.php command-line utility

  bin/host-sanity-config.php --bin free-space free-space-check /tmp

• Configure endpoint for use with HTTP server:

  • Dev use only

    • start the webservice command-line utility

    bin/webservice

  • Production or Dev

    • create a symlink to healthsvc/web dir in existing http root

    ln -s /var/www/healthsvc/web /var/www/html/healthsvc

    • --OR--
    • use the healthsvc/web dir as the http root:

    # nginx example
    server {
    ...
        root   /var/www/healthsvc/web;
    ...
    }

• Test the web/host-sanity.php webservice endpoint

  • For example, using curl command-line utility

    curl http://localhost:8000/host-sanity.php

• Example web/host-sanity.php response body when tests in "success" status (200/OK response code)

  {
   "hostname": "my-host",
   "exec_exit_status": [],
   "health_status_time": "2018-12-11T21:51:36-08:00",
   "health_status_ttl": 0,
   "message": "total success",
   "health_info": {
       "free-space": {
           "stdout": [
               "ok: '\/tmp' has 81% free disk space"
           ]
       }
   },
   "health_success": [
       "free-space"
   ],
   "health_warn": [],
   "health_failure": []
  }

• Example web/host-sanity.php response body when one or more tests has "failure" status (500/Internal Server Error response code)

  {
   "hostname": "my-host",
   "exec_exit_status": {
       "free-space": 3
   },
   "health_status_time": "2018-12-11T21:58:45-08:00",
   "health_status_ttl": 0,
   "message": "one or more failures",
   "health_info": [],
   "health_success": [],
   "health_warn": [],
   "health_failure": {
       "free-space": {
           "stdout": [
               "'\/tmp' has only 10% free disk space (20% is minimum required)"
           ]
       }
   }
  }

Usage in Existing Projects

• See PHP usage documentation for more details.

• Use Composer to add to an existing project.

  composer require katmore/healthsvc

Unit Tests

• docs/coverage.txt: unit test coverage report
• phpunit.xml.dist: PHPUnit configuration file
• tests/phpunit: source code for unit tests

To perform unit tests, execute phpunit located in the vendor/bin directory.

vendor/bin/phpunit

The tests.sh wrapper script is provided for convenience.

./tests.sh

Legal

"Healthsvc" is distributed under the terms of the MIT license or the GPLv3 license.

Copyright (c) 2018-2019, Doug Bird. All rights reserved.