# monit-docker project
[](https://pypi.org/project/monit-docker/)
[](https://pypi.org/project/monit-docker/)
[](https://hub.docker.com/r/decryptus/monit-docker)
[](https://monit-docker.readthedocs.io/)
monit-docker is a free and open-source, we develop it to monitor container status or resources
and execute some commands inside containers or manage containers with dockerd, for example:
- reload php-fpm if memory usage is too high
- reload php-fpm if no free space in /dev/shm
- restart container if status is not running
- remove all containers
## Table of contents
1. [Quickstart](#quickstart)
2. [Installation](#installation)
3. [Environment variables](#environment_variables)
4. [Sub-command: monit](#sub-command_monit)
1. [Basic commands](#monit_basic_commands)
2. [Advanced commands](#monit_advanced_commands)
3. [Container informations with exit codes](#monit_container_informations)
4. [monit-docker with M/Monit](#monit_with_mmonit)
5. [Sub-command: stats](#sub-command_stats)
1. [Basic commands](#stats_basic_commands)
2. [Advanced commands](#stats_advanced_commands)
## <a name="quickstart"></a>Quickstart
Using monit-docker in Docker with crond
`docker-compose up -d`
See [docker-compose.yml](docker-compose.yml) and MONIT\_DOCKER\_CRONS environment variable to configure commands.
## <a name="installation"></a>Installation
`pip install monit-docker`
## <a name="environment_variables"></a>Environment variables
| Variable | Description | Default |
|:---------------------------|:----------------------------|:--------|
| `MONIT_DOCKER_CONFIG` | Configuration file contents<br />(e.g. `export MONIT_DOCKER_CONFIG="$(cat monit-docker.yml)"`) | |
| `MONIT_DOCKER_CONFFILE` | Configuration file path | /etc/monit-docker/monit-docker.yml |
| `MONIT_DOCKER_LOGFILE` | Log file path | /var/log/monit-docker/monit-docker.log |
| `MONIT_DOCKER_RUNTIMEDIR` | Runtime directory path | /run/monit-docker |
## <a name="sub-command_monit"></a>Sub-command: monit
### <a name="monit_basic_commands"></a>Basic commands
Restart containers with name starts with foo if memory usage percentage > 60% or cpu usage percentage > 90%:
`monit-docker --name 'foo*' monit --cmd-if 'mem_percent > 60 ? restart' --cmd-if 'cpu_percent > 90 ? restart'`
Stop containers with name starts with bar or foo and if cpu usage percentage greater than 60% and less than 70%:
`monit-docker --name 'bar*' --name 'foo*' monit --cmd-if '60 > cpu_percent < 70 ? stop'`
Kill containers with name starts with bar and status equal to pause or running:
`monit-docker --name 'bar*' monit --cmd-if 'status in (pause,running) ? kill'`
You can also use status argument, for example, restart containers with status paused or exited:
`monit-docker -s paused -s exited monit --cmd 'restart'`
Generate containers pidfile:
`monit-docker monit --rsc pid`
Reload php-fpm in container with image name contains /php-fpm/ if memory usage greater than 100 MiB:
`monit-docker --image '*/php-fpm/*' monit --cmd-if 'mem_usage > 100 MiB ? (kill -USR2 1)'`
Reload php-fpm in container with image name contains /php-fpm/ if /dev/shm percentage usage greater than 80%:
`monit-docker --image '*/php-fpm/*' monit --cmd '(bash -c "[ $(df /dev/shm | sed \"s/\%//;\$!d\" | awk \"{print \$5}\") -gt 80 ] && kill -USR2 1")'`
### <a name="monit_advanced_commands"></a>Advanced commands with configuration file or environment variable MONIT\_DOCKER\_CONFIG
##### Run commands with aliases declared in configuration file (e.g.: [monit-docker.yml.example](etc/monit-docker/monit-docker.yml.example)):
Restart container id 4c01db0b339c if condition alias @status\_not\_running is true:
`monit-docker --id 4c01db0b339c monit --cmd-if '@status_not_running ? restart'`
Execute commands alias @start\_pause containers with name starts with foo if condition alias @status\_not\_running is true:
`monit-docker --name 'foo*' monit --cmd-if '@status_not_running ? @start_pause'`
Remove force container group php if status is equal to running:
`monit-docker --ctn-group php monit --cmd-if 'status == running ? @remove_force'`
Restart containers group nodejs if memory usage percentage > 10% and cpu usage percentage > 60%:
`monit-docker --ctn-group nodejs monit --cmd-if '@mem_gt_10pct_and_cpu_gt_60pct ? restart'`
Remove force all containers:
`monit-docker monit --cmd '@remove_force'`
### <a name="monit_container_informations"></a>Container informations with exit codes
##### Container status
Run command below to get status with exit code for container named foo\_php\_fpm:
`monit-docker --name foo_php_fpm monit --rsc status`
An error occurred if exit code is greater than 100.
| Exit code | Description |
|:----------|:------------|
| 0 | Running |
| 10 | Created |
| 20 | Paused |
| 30 | Restarting |
| 40 | Removing |
| 50 | Exited |
| 60 | Dead |
| 114 | Not found |
##### Container CPU usage percentage
Run command below to get CPU usage percentage with exit code for container named foo\_php\_fpm:
`monit-docker --name foo_php_fpm monit --rsc cpu_percent`
An error occurred if exit code is greater than 100.
##### Container memory usage percentage
Run command below to get memory usage percentage with exit code for container named foo\_php\_fpm:
`monit-docker --name foo_php_fpm monit --rsc mem_percent`
An error occurred if exit code is greater than 100.
### <a name="monit_with_mmonit"></a>monit-docker with M/Monit
We can also monitoring containers cpu\_percent and mem\_percent resources with [M/Monit](https://mmonit.com).
##### Configuration examples
```
check program docker.foo_php_fpm.status with path "/usr/bin/monit-docker --name foo_php_fpm monit --rsc status"
group monit-docker
if status = 114 for 2 cycles then alert # container not found
if status != 0 for 2 cycles then exec "/usr/bin/monit-docker --name foo_php_fpm monit --cmd restart" # container not running
check program docker.foo_php_fpm.cpu with path "/usr/bin/monit-docker -s running --name foo_php_fpm monit --rsc cpu_percent"
group monit-docker
if status > 100 for 2 cycles then alert
if status > 70 for 2 cycles then alert
if status > 80 for 4 cycles then exec "/usr/bin/monit-docker --name foo_php_fpm monit --cmd reload"
check program docker.foo_php_fpm.mem with path "/usr/bin/monit-docker -s running --name foo_php_fpm monit --rsc mem_percent"
group monit-docker
if status > 100 for 2 cycles then alert
if status > 70 for 2 cycles then alert
if status > 80 for 4 cycles then exec "/usr/bin/monit-docker --name foo_php_fpm monit --cmd '(kill -USR2 1)'"
check program docker.foo_php_fpm.pid with pidfile /run/monit-docker/foo_php_fpm.pid
group monit-docker
if changed pid then alert
```
## <a name="sub-command_stats"></a>Sub-command: stats
### <a name="stats_basic_commands"></a>Basic commands
Get all resources statistics for all containers in json format:
`monit-docker stats --output json`
```json
{
"flamboyant_chaplygin": {
"status": "running",
"mem_percent": 0.03,
"net_tx": "0.0 B",
"cpu_percent": 0,
"mem_usage": "2.52 MiB",
"io_read": "3.5 MB",
"io_write": "0.0 B",
"net_rx": "25.2 kB",
"mem_limit": "7.27 GiB",
"pid": "3943"
}
}
{
"practical_proskuriakova": {
"status": "running",
"mem_percent": 0.04,
"net_tx": "0.0 B",
"cpu_percent": 0,
"mem_usage": "2.61 MiB",
"io_read": "24.6 kB",
"io_write": "0.0 B",
"net_rx": "25.0 kB",
"mem_limit": "7.27 GiB",
"pid": "3990"
}
}
```
Get all resources statistics for all containers in text format:
`monit-docker stats --output text`
```
flamboyant_chaplygin|mem_usage:2.52 MiB|mem_limit:7.27 GiB|mem_percent:0.03|cpu_percent:0.0|io_read:3.5 MB|io_write:0.0 B|net_tx:0.0 B|net_rx:43.5 kB|status:running
practical_proskuriakova|mem_usage:2.61 MiB|mem_limit:7.27 GiB|mem_percent:0.04|cpu_percent:0.0|io_read:24.6 kB|io_write:0.0 B|net_tx:0.0 B|net_rx:43.3 kB|status:running
```
### <a name="stats_advanced_commands"></a>Advanced commands with configuration file or environment variable MONIT\_DOCKER\_CONFIG
Get status and memory usage for group nodejs:
`monit-docker --ctn-group nodejs stats --rsc status --rsc mem_usage`
Raw data
{
"_id": null,
"home_page": "https://github.com/decryptus/monit-docker",
"name": "monit-docker",
"maintainer": "",
"docs_url": null,
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*",
"maintainer_email": "",
"keywords": "",
"author": "Adrien Delle Cave",
"author_email": "pypi@doowan.net",
"download_url": "",
"platform": null,
"description": "# monit-docker project\n\n[](https://pypi.org/project/monit-docker/)\n[](https://pypi.org/project/monit-docker/)\n[](https://hub.docker.com/r/decryptus/monit-docker)\n[](https://monit-docker.readthedocs.io/)\n\nmonit-docker is a free and open-source, we develop it to monitor container status or resources\nand execute some commands inside containers or manage containers with dockerd, for example:\n - reload php-fpm if memory usage is too high\n - reload php-fpm if no free space in /dev/shm\n - restart container if status is not running\n - remove all containers\n\n## Table of contents\n1. [Quickstart](#quickstart)\n2. [Installation](#installation)\n3. [Environment variables](#environment_variables)\n4. [Sub-command: monit](#sub-command_monit)\n 1. [Basic commands](#monit_basic_commands)\n 2. [Advanced commands](#monit_advanced_commands)\n 3. [Container informations with exit codes](#monit_container_informations)\n 4. [monit-docker with M/Monit](#monit_with_mmonit)\n5. [Sub-command: stats](#sub-command_stats)\n 1. [Basic commands](#stats_basic_commands)\n 2. [Advanced commands](#stats_advanced_commands)\n\n## <a name=\"quickstart\"></a>Quickstart\n\nUsing monit-docker in Docker with crond\n\n`docker-compose up -d`\n\nSee [docker-compose.yml](docker-compose.yml) and MONIT\\_DOCKER\\_CRONS environment variable to configure commands.\n\n## <a name=\"installation\"></a>Installation\n\n`pip install monit-docker`\n\n## <a name=\"environment_variables\"></a>Environment variables\n\n| Variable | Description | Default |\n|:---------------------------|:----------------------------|:--------|\n| `MONIT_DOCKER_CONFIG` | Configuration file contents<br />(e.g. `export MONIT_DOCKER_CONFIG=\"$(cat monit-docker.yml)\"`) | |\n| `MONIT_DOCKER_CONFFILE` | Configuration file path | /etc/monit-docker/monit-docker.yml |\n| `MONIT_DOCKER_LOGFILE` | Log file path | /var/log/monit-docker/monit-docker.log |\n| `MONIT_DOCKER_RUNTIMEDIR` | Runtime directory path | /run/monit-docker |\n\n## <a name=\"sub-command_monit\"></a>Sub-command: monit\n\n### <a name=\"monit_basic_commands\"></a>Basic commands\n\nRestart containers with name starts with foo if memory usage percentage > 60% or cpu usage percentage > 90%:\n\n`monit-docker --name 'foo*' monit --cmd-if 'mem_percent > 60 ? restart' --cmd-if 'cpu_percent > 90 ? restart'`\n\nStop containers with name starts with bar or foo and if cpu usage percentage greater than 60% and less than 70%:\n\n`monit-docker --name 'bar*' --name 'foo*' monit --cmd-if '60 > cpu_percent < 70 ? stop'`\n\nKill containers with name starts with bar and status equal to pause or running:\n\n`monit-docker --name 'bar*' monit --cmd-if 'status in (pause,running) ? kill'`\n\nYou can also use status argument, for example, restart containers with status paused or exited:\n\n`monit-docker -s paused -s exited monit --cmd 'restart'`\n\nGenerate containers pidfile:\n\n`monit-docker monit --rsc pid`\n\nReload php-fpm in container with image name contains /php-fpm/ if memory usage greater than 100 MiB:\n\n`monit-docker --image '*/php-fpm/*' monit --cmd-if 'mem_usage > 100 MiB ? (kill -USR2 1)'`\n\nReload php-fpm in container with image name contains /php-fpm/ if /dev/shm percentage usage greater than 80%:\n\n`monit-docker --image '*/php-fpm/*' monit --cmd '(bash -c \"[ $(df /dev/shm | sed \\\"s/\\%//;\\$!d\\\" | awk \\\"{print \\$5}\\\") -gt 80 ] && kill -USR2 1\")'`\n\n### <a name=\"monit_advanced_commands\"></a>Advanced commands with configuration file or environment variable MONIT\\_DOCKER\\_CONFIG\n\n##### Run commands with aliases declared in configuration file (e.g.: [monit-docker.yml.example](etc/monit-docker/monit-docker.yml.example)):\n\nRestart container id 4c01db0b339c if condition alias @status\\_not\\_running is true:\n\n`monit-docker --id 4c01db0b339c monit --cmd-if '@status_not_running ? restart'`\n\nExecute commands alias @start\\_pause containers with name starts with foo if condition alias @status\\_not\\_running is true:\n\n`monit-docker --name 'foo*' monit --cmd-if '@status_not_running ? @start_pause'`\n\nRemove force container group php if status is equal to running:\n\n`monit-docker --ctn-group php monit --cmd-if 'status == running ? @remove_force'`\n\nRestart containers group nodejs if memory usage percentage > 10% and cpu usage percentage > 60%:\n\n`monit-docker --ctn-group nodejs monit --cmd-if '@mem_gt_10pct_and_cpu_gt_60pct ? restart'`\n\nRemove force all containers:\n\n`monit-docker monit --cmd '@remove_force'`\n\n### <a name=\"monit_container_informations\"></a>Container informations with exit codes\n\n##### Container status\n\nRun command below to get status with exit code for container named foo\\_php\\_fpm:\n\n`monit-docker --name foo_php_fpm monit --rsc status`\n\nAn error occurred if exit code is greater than 100.\n\n| Exit code | Description |\n|:----------|:------------|\n| 0 | Running |\n| 10 | Created |\n| 20 | Paused |\n| 30 | Restarting |\n| 40 | Removing |\n| 50 | Exited |\n| 60 | Dead |\n| 114 | Not found |\n\n##### Container CPU usage percentage\n\nRun command below to get CPU usage percentage with exit code for container named foo\\_php\\_fpm:\n\n`monit-docker --name foo_php_fpm monit --rsc cpu_percent`\n\nAn error occurred if exit code is greater than 100.\n\n##### Container memory usage percentage\n\nRun command below to get memory usage percentage with exit code for container named foo\\_php\\_fpm:\n\n`monit-docker --name foo_php_fpm monit --rsc mem_percent`\n\nAn error occurred if exit code is greater than 100.\n\n### <a name=\"monit_with_mmonit\"></a>monit-docker with M/Monit\n\nWe can also monitoring containers cpu\\_percent and mem\\_percent resources with [M/Monit](https://mmonit.com).\n\n##### Configuration examples\n\n```\ncheck program docker.foo_php_fpm.status with path \"/usr/bin/monit-docker --name foo_php_fpm monit --rsc status\"\n group monit-docker\n if status = 114 for 2 cycles then alert # container not found\n if status != 0 for 2 cycles then exec \"/usr/bin/monit-docker --name foo_php_fpm monit --cmd restart\" # container not running\n\ncheck program docker.foo_php_fpm.cpu with path \"/usr/bin/monit-docker -s running --name foo_php_fpm monit --rsc cpu_percent\"\n group monit-docker\n if status > 100 for 2 cycles then alert\n if status > 70 for 2 cycles then alert\n if status > 80 for 4 cycles then exec \"/usr/bin/monit-docker --name foo_php_fpm monit --cmd reload\"\n\ncheck program docker.foo_php_fpm.mem with path \"/usr/bin/monit-docker -s running --name foo_php_fpm monit --rsc mem_percent\"\n group monit-docker\n if status > 100 for 2 cycles then alert\n if status > 70 for 2 cycles then alert\n if status > 80 for 4 cycles then exec \"/usr/bin/monit-docker --name foo_php_fpm monit --cmd '(kill -USR2 1)'\"\n\ncheck program docker.foo_php_fpm.pid with pidfile /run/monit-docker/foo_php_fpm.pid\n group monit-docker\n if changed pid then alert\n\n```\n\n## <a name=\"sub-command_stats\"></a>Sub-command: stats\n\n### <a name=\"stats_basic_commands\"></a>Basic commands\n\nGet all resources statistics for all containers in json format:\n\n`monit-docker stats --output json`\n\n```json\n{\n \"flamboyant_chaplygin\": {\n \"status\": \"running\",\n \"mem_percent\": 0.03,\n \"net_tx\": \"0.0 B\",\n \"cpu_percent\": 0,\n \"mem_usage\": \"2.52 MiB\",\n \"io_read\": \"3.5 MB\",\n \"io_write\": \"0.0 B\",\n \"net_rx\": \"25.2 kB\",\n \"mem_limit\": \"7.27 GiB\",\n \"pid\": \"3943\"\n }\n}\n{\n \"practical_proskuriakova\": {\n \"status\": \"running\",\n \"mem_percent\": 0.04,\n \"net_tx\": \"0.0 B\",\n \"cpu_percent\": 0,\n \"mem_usage\": \"2.61 MiB\",\n \"io_read\": \"24.6 kB\",\n \"io_write\": \"0.0 B\",\n \"net_rx\": \"25.0 kB\",\n \"mem_limit\": \"7.27 GiB\",\n \"pid\": \"3990\"\n }\n}\n```\n\nGet all resources statistics for all containers in text format:\n\n`monit-docker stats --output text`\n\n```\nflamboyant_chaplygin|mem_usage:2.52 MiB|mem_limit:7.27 GiB|mem_percent:0.03|cpu_percent:0.0|io_read:3.5 MB|io_write:0.0 B|net_tx:0.0 B|net_rx:43.5 kB|status:running\npractical_proskuriakova|mem_usage:2.61 MiB|mem_limit:7.27 GiB|mem_percent:0.04|cpu_percent:0.0|io_read:24.6 kB|io_write:0.0 B|net_tx:0.0 B|net_rx:43.3 kB|status:running\n```\n\n### <a name=\"stats_advanced_commands\"></a>Advanced commands with configuration file or environment variable MONIT\\_DOCKER\\_CONFIG\n\nGet status and memory usage for group nodejs:\n\n`monit-docker --ctn-group nodejs stats --rsc status --rsc mem_usage`\n\n\n",
"bugtrack_url": null,
"license": "License GPL-3",
"summary": "monit-docker",
"version": "0.0.50",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "450126f83a158dd2b683f404d35f921c26276963030cae3c68de47575356c98d",
"md5": "1fec4d1ba6f0d5de12a7a481b2205873",
"sha256": "f7e2c15444da683e49b32b797d3c11665f2871add1b1d5a046b4104d2e7cab59"
},
"downloads": -1,
"filename": "monit_docker-0.0.50-py2-none-any.whl",
"has_sig": false,
"md5_digest": "1fec4d1ba6f0d5de12a7a481b2205873",
"packagetype": "bdist_wheel",
"python_version": "py2",
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*",
"size": 25820,
"upload_time": "2023-01-16T11:31:28",
"upload_time_iso_8601": "2023-01-16T11:31:28.240053Z",
"url": "https://files.pythonhosted.org/packages/45/01/26f83a158dd2b683f404d35f921c26276963030cae3c68de47575356c98d/monit_docker-0.0.50-py2-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a0104804c9038716dfa0f17cb57a327aaddc25ef9b2f7735c31aa745e7cad1d6",
"md5": "215c0139f10ccf80a62c62cb4781716a",
"sha256": "cc8f904d5a9ef5bc675c7dc5c6b853e1a758d1db266461561c2d81fc141b7266"
},
"downloads": -1,
"filename": "monit_docker-0.0.50-py3-none-any.whl",
"has_sig": false,
"md5_digest": "215c0139f10ccf80a62c62cb4781716a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*",
"size": 25818,
"upload_time": "2023-01-16T11:31:37",
"upload_time_iso_8601": "2023-01-16T11:31:37.752247Z",
"url": "https://files.pythonhosted.org/packages/a0/10/4804c9038716dfa0f17cb57a327aaddc25ef9b2f7735c31aa745e7cad1d6/monit_docker-0.0.50-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-16 11:31:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "decryptus",
"github_project": "monit-docker",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "monit-docker"
}
JSON
