PHPackages geoffroy-aubry/supervisor - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Logging & Monitoring](/categories/logging) 4. / 5. geoffroy-aubry/supervisor ActiveLibrary[Logging & Monitoring](/categories/logging) geoffroy-aubry/supervisor ========================= Oversee script execution, recording stdout, stderr and exit code with timestamping, and ensure email notifications will be sent (on start, success, warning or error). v1.8.1(11y ago)87.4k1LGPL-3.0+PHP Since Oct 8Pushed 11y ago1 watchersCompare [ Source](https://github.com/geoffroy-aubry/Supervisor)[ Packagist](https://packagist.org/packages/geoffroy-aubry/supervisor)[ RSS](/packages/geoffroy-aubry-supervisor/feed)WikiDiscussions stable Synced today READMEChangelogDependencies (3)Versions (15)Used By (1) Supervisor ========== [](#supervisor) [![Latest stable version](https://camo.githubusercontent.com/9f84a6f3cd82376401745b3b6618d5156e3be7e3bbd13f5f9b2106db88fc4dc8/68747470733a2f2f706f7365722e707567782e6f72672f67656f6666726f792d61756272792f53757065727669736f722f762f737461626c652e706e67 "Latest stable version")](https://packagist.org/packages/geoffroy-aubry/Supervisor)[![Build Status](https://camo.githubusercontent.com/8762a2906c000988cfae09e080dd6ef43a764552e1b9c5a07fc3159ad6e7ea45/68747470733a2f2f7365637572652e7472617669732d63692e6f72672f67656f6666726f792d61756272792f53757065727669736f722e706e673f6272616e63683d737461626c65)](http://travis-ci.org/geoffroy-aubry/Supervisor) *[Estimated code coverage](https://travis-ci.org/geoffroy-aubry/Supervisor): 87% (553 of 638 lines).* Oversee script execution, recording `stdout`, `stderr` and exit code with timestamping, and ensure email notifications will be sent (on startup, success, warning or error)… plus many other features. **Technologies** : Supervisor is in Bash, only unit tests are in PHP. **Supported OS** : Debian/Ubuntu Linux, FreeBSD/OS X. Table of Contents ----------------- [](#table-of-contents) - [Features](#features) - [General](#general) - [Notifications](#notifications) - [Ergonomics](#ergonomics) - [Code quality](#code-quality) - [Requirements](#requirements) - [Usage](#usage) - [Help on command prompt](#help-on-command-prompt) - [Exit status](#exit-status) - [Successful execution](#successful-execution) - [Errors](#errors) - [Tags](#tags) - [Locks](#locks) - [Customized mails](#customized-mails) - [Supervisor supervised](#supervisor-supervised) - [Archiving](#archiving) - [Monitoring](#monitoring) - [Summary](#summary) - [Installation](#installation) - [Copyrights & licensing](#copyrights--licensing) - [Change log](#change-log) - [Continuous integration](#continuous-integration) - [Git branching model](#git-branching-model) Features -------- [](#features) ### General [](#general) - Oversee script execution, recording `stdout`, `stderr` and exit code - Prefix each line of `stdout` with timestamps with hundredths of seconds. - An execution ID uniquely identify each script execution. Used in: `supervisor.info.log`, `supervisor.error.log`, `_.info.log`and `_.error.log`. - Possibility to block parallel script execution *(only on Debian/Ubuntu Linux)*. Useful if an execution takes too long… - You can specify a configuration file to load in addition to the default one (overloading). - Entirely configurable tag system allowing executed scripts to dynamically specify via `stdout`warning, mailto, mail attachment, instigator… - Automatic log archiving mechanism. - Display a summary of supervisor's activity during last days, including final status per day and per supervised script. - Handle CSV output, with definition of field separator, field enclosure and number of the field to watch in configuration file. - Add proper signal handling and interrupts: `SIGHUP`, `SIGINT`, `SIGQUIT` and `SIGTERM`now transmitted to supervised script. ### Notifications [](#notifications) - Ensure email notifications will be sent on following events (configurable): startup, success, warning or error. Catch exit code, fatal error, exceptions… - All mail contains content of `stdout` and `stderr` of executed script in Gzip attachment. - Mails are fully customizable. Just provide your file on command line. - Possibility to inject multiple external parameters on command line into customized emails. - Supervisor itself is monitoring by another process, sending critical email notifications using an exponential backoff algorithm in minute increments. ### Ergonomics [](#ergonomics) - During supervision and in addition of all log files, Supervisor displays in real time outputs, warning and errors of overseen script, adding timestamp and respecting both colors and indentation. Name of all log files are printed too. ### Code quality [](#code-quality) - Bash code executed with following directives: - `set -o nounset`: treat unset variables and parameters other than the special parameters `@` or `*` as an error when performing parameter expansion. An error message will be written to the standard error, and a non-interactive shell will exit. - `set -o pipefail`: The return value of a pipeline is the value of the last (rightmost) command to exit with a non-zero status, or zero if all commands in the pipeline exit successfully. - A lot of unit tests (via [PHPUnit](https://github.com/sebastianbergmann/phpunit/) through a PHP wrapper) covering almost the whole application. Requirements ------------ [](#requirements) - Bash v4 *(2009)* and above - [mutt](http://www.mutt.org/), to send email notifications (`apt-get install mutt`, or `brew install mutt`) - Unit tests require PHP >= 5.3.3 and Xdebug - On FreeBSD/OS X only, you need to install these GNU tools: ``` $ brew install coreutils $ brew install gnu-sed $ brew install gawk ``` Tested on Debian/Ubuntu Linux and FreeBSD/OS X. Usage ----- [](#usage) ### Help on command prompt [](#help-on-command-prompt) Displayed by: ``` $ supervisor.sh [-h|--help] ``` [![Help on command prompt](doc/screenshots/supervisor.png)](doc/screenshots/supervisor.png) ##### Text version [](#text-version) ``` Description Oversee script execution, recording stdout, stderr and exit code with timestamping, and ensure email notifications will be sent (on start, success, warning or error). Usage supervisor [OPTION]… [] supervisor [-c ] --archive= supervisor [-c ] --monitor supervisor [-c ] --summarize Options --archive= Archive in Gzip supervisor's logs older than . -c , --conf= Specify a configuration file to load in addition to the default one, namely '/conf/supervisor-dist.sh'. --customized-mails= Path to a Bash script customizing sent mails by redefining some of the sendMailOn[Init|Success|Warning|Error]() functions. See --param option. --exec-id= Allow to force execution id, used in mails and name of logs. By default: YYYYMMDDHHIISS_XXXXX, where X are random digits. --extra-param-mode=[only-value|with-name|none] Two extra parameters are added to the end of : a unique execution ID and name of file recording script's stderr. with-name mode prefixes values with '--exec-id=' and '--error-log-file=' respectively. By default: only-value. -h, --help Display this help. --mail-instigator= Specify who executed the supervisor. --mail-to= Add a new recipient's email address. Multiple --mail-to options may be used. --monitor Check whether supervisor's error log file is empty. If not, then send critical email notifications using an exponential backoff algorithm in minute increments. Typically called every minute with a cron job: * * * * * /path/to/supervisor.sh --conf= --monitor -p =, --param== Allow to inject multiple external parameters into customized emails. Assign the value to the Bash variable $EXT_. See --customized-mails option. --summarize= Display a summary of supervisor's activity during last days, including final status per day and per supervised script. Also send this summary by email. Executable script to oversee. Optional oversaw script's parameters. Exit status 0 if and only if no error 65 Missing script name! 66 Script '…' not found! 67 Script '…' is not executable! 68 Exit code changed from 0 to 68 due to errors. 69 Another instance of '…' is still running with supervisor! 71 Customized mails file not found: '…' 72 Invalid Mutt command: '…' xxx Any code not null returned by user script ``` ### Exit status [](#exit-status) List of exit status: - `0` If and only if no error - `65` Missing script name! - `66` Script '…' not found! - `67` Script '…' is not executable! - `68` Exit code changed from 0 to 68 due to errors. - `69` Another instance of '…' is still running with supervisor! - `71` Customized mails file not found: '…' - `72` Invalid Mutt command: '…' - Any code not null returned by user script ### Successful execution [](#successful-execution) An execution is successful if and only if `stderr` is empty, exit status is `0` and there are no warnings. A short example, here in Bash but no matter the language: ``` #!/usr/bin/env bash echo Title: echo -e '\033[0;30m┆\033[0m \033[1;32mgreen level 1' echo -e '\033[0;30m┆\033[0m \033[0;30m┆\033[0m \033[1;33myellow level 2' echo 'END' ``` Output: [![Successful output](doc/screenshots/supervisor-successful-stdout.png)](doc/screenshots/supervisor-successful-stdout.png) If `SUPERVISOR_MAIL_SEND_ON_STARTUP` is set to `1` in configuration file: [![Mail on startup](doc/screenshots/supervisor-successful-mail-startup.png)](doc/screenshots/supervisor-successful-mail-startup.png) Note that Supervisor add two parameters in addition of script parameters: - a unique execution ID - name of file recording script's `stderr` If `SUPERVISOR_MAIL_SEND_ON_SUCCESS` is set to `1` in configuration file: [![Mail on success](doc/screenshots/supervisor-successful-mail-success.png)](doc/screenshots/supervisor-successful-mail-success.png) Content of `supervisor.info.log.20131006223705_01765.gz` attachment: ``` 2013-10-06 22:37:05 58cs;20131006223705_01765;/usr/local/lib/supervisor/tests/resources/bash_colored_simple.sh;START 2013-10-06 22:37:05 78cs;20131006223705_01765;/usr/local/lib/supervisor/tests/resources/bash_colored_simple.sh;OK ``` Content of `bash_colored_simple.sh.20131006223705_01765.info.log.gz` attachment: ``` 2013-10-06 22:37:05 58cs;[SUPERVISOR] START 2013-10-06 22:37:05 74cs;Title: 2013-10-06 22:37:05 75cs;┆ green level 1 2013-10-06 22:37:05 76cs;┆ ┆ yellow level 2 2013-10-06 22:37:05 77cs;END 2013-10-06 22:37:05 78cs;[SUPERVISOR] OK ``` Note that colors are stripped but indentation is kept. ### Errors [](#errors) An execution end in error status if either `stderr` is not empty or if exit status is different from `0`. #### PHP fatal error [](#php-fatal-error) We will oversee a PHP script throwing a fatal error: ```