# Minimon
**minimon** is a 'minimal' (as in minimal music) IT monitoring tool for the command line.
Compared to lots of other IT monitoring solutions it has the following main attributes:
- It follows a 'configuration as application' approach, i.e. instead of configuring your monitoring
via UI you will 'write' your whole executable application yourself!
(see example below for clarification)
- It's ultra-flexible by being more an 'automation with functional pipes' framework letting
you do anything you can automate rather than a configurable application
- It's _minimal_ also in terms of a hobby project. Don't expect something which competes with
Checkmk, Prometheus, etc.
- Since you have to implement / modify the main executable using plain Python (in contrast to
configuring some black box application), you might get into Python programming rather quickly as
a side effect.
There are some technical properties and maxims you might be interested in as well:
- `textual` / `rich` based
- Heavy use of asynchronous programming
- Functional approaches wherever possible
- `asyncssh` instead of `paramiko`
## Installation
While you can just clone and use minimon, the intended way to use it is to install it from PyPI.org
or run it from inside a virtual environment.
Install it locally using `pip`:
```sh
[<PYTHON> -m] pip[3] install [--user] [--upgrade] minimon
```
Currently you need at least Python **v3.10+** installed in order to run **minimon**. In case your
system provides older versions only, consider using `pyenv` to install any other version next
to your system-Python.
## Example
The following snippet is taken from a recent **minimon** installation folder, e.g.
`~/.local/lib/python3.11/site-packages/minimon/sites/mvm.py` and shows a poorly minimalistic but
working example of a fully functional **minimon** site:
```python
from minimon import *
from minimon.plugins import df, ps
with Monitor("MVM"):
@view(("host", [Host("localhost")]))
async def local_resources(host: Host) -> AInsights:
"""This async generator will be invoked by the above `view` and run continuously to
gather and yield monitoring data"""
async for insight in Bundler(
ps=ps.generate(host) | ps.parse() | ps.check(),
df=df.generate(host) | df.parse() | df.check(),
):
yield insight
```
Create/copy your own file to test and modify:
```sh
mkdir minimon-sites 130 ↵
cp ~/.local/lib/python3.11/site-packages/minimon/sites/mvm.py minimon-sites
chmod +x minimon-sites/mvm.py
```
Start it by executing
```
minimon-sites/mvm.py
```
## Why (do I do this?)
- async
- functional
- testability
- bullet proof
## Todo
### Core / enabler:
- [ ] Fix: CTRL-C hang due to non terminated tasks
- [ ] Read ssh passwords once on startup
- [x] Provide a way to use data propagating through functions by different consumers
- [x] Provide monadic (async) function chaining
- [x] Support for endless processes ("dmesg -w")
- [x] View: arbitrary number of parameters (0, 1, 2 for now)
- [x] Host-config: parametrize check-pipe
- [x] Fix: Styled log output, see https://stackoverflow.com/questions/77716718
- [ ] Show Links (e.g. to monitoring)
- [ ] Mature hierarchic error handling/propagation and restart management
- [ ] Capture and persist metrics
- [ ] Recognize (dis)appearance of found entities (df-mountpoints, network adapters, etc)
- [ ] Support for remote APIs
- [ ] Support for multi line scripts
- [ ] Support for optional `su -c ..`
- [ ] Recognize check state transitions -> notifications
- [ ] Provide ways to interact
- [ ] Improve logging: to file, log threads, log task context
- [ ] Let core run in background
- [ ] Check windows support
- [ ] research: send mails
### Visuals
- [ ] visualize metrics
### Reactions (automatic actions)
- [ ] send build break notifications
- [ ] run scripts open/close branches
### Actions (user interaction)
- [ ] rebuild failed jobs
- [ ] kill/delete containers/volumes/tags/images
- [ ] open/close branches
- [ ] cleanup workspace(s)
### SSH-Plugins:
- [ ] disk space
- [ ] ram
- [ ] cpu usage over time
- [ ] network usage per process
- [ ] android: check battery
- [ ] docker: number containers/images/volumes/networks/build cache
- [ ] wrong permissions/ownerships `/home/jenkins -user root`
- [ ] unused directories
### API-Plugins:
- [ ] docker: per container: cpu / ram / runtime
- jenkins-jobs
- [ ] job tree
- [ ] warning about certain job results (sheriffing)
- [ ] branch sheriffing state
- [ ]job <=> containers association
- [ ]nexus artifacts
## Development & Contribution
### Setup
For active development you need to have `poetry` and `pre-commit` installed
```sh
python3 -m pip install --upgrade --user poetry pre-commit
poetry self add poetry-bumpversion
git clone git@projects.om-office.de:frans/minimon.git
cd minimon
pre-commit install
# if you need a specific version of Python inside your dev environment
poetry env use ~/.pyenv/versions/3.10.4/bin/python3
poetry install
```
### Workflow
* Create/test/commit changes and check commits via `pre-commit`
* after work is done locally:
- bump version using `poetry version patch`
- build and check a package
```sh
poetry build && \
twine check dist/* &&
python3 -m pip uninstall -y minimon && \
python3 -m pip install --user dist/minimon-$(grep -E "^version.?=" pyproject.toml | cut -d '"' -f 2)-py3-none-any.whl
```
- check installed package
- publish the new package `poetry publish --build`
- commit new version && push
## License
For all code contained in this repository the rules of GPLv3 apply unless
otherwise noted. That means that you can do what you want with the source
code as long as you make the files with their original copyright notice
and all modifications available.
See [GNU / GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html) for details.
This project is not free for machine learning. If you're using any content
of this repository to train any sort of machine learned model (e.g. LLMs),
you agree to make the whole model trained with this repository and all data
needed to train (i.e. reproduce) the model publicly and freely available
(i.e. free of charge and with no obligation to register to any service) and
make sure to inform the author (me, frans.fuerst@protonmail.com) via email
how to get and use that model and any sources needed to train it.
## Good to know
### Gather some information
- `free -b`
- `df`
- `dmesg -w`
- `logcat`
- `docker image list -aq | uniq | wc`
- `docker container list -aq | wq`
- https://www.baeldung.com/linux/get-cpu-usage
- `vmstat -n 5`
- `ss --numeric --resolve --processes --info`
### `sshd` for Android
- SimpleSSH
- `host <IP>` -> hostname
- `scp -P2222 ~/.ssh/id_ed25519.pub <HOST>:authorized_keys`
- `ssh -p2222 <HOST> "su -c 'dmesg -w'"`
- `ssh -p2222 <HOST> "su -c 'df'"`
- `ssh -p2222 <HOST> "su -c 'top'"`
- `ssh -p2222 <HOST> "su -c 'dumpsys battery'"`
Raw data
{
"_id": null,
"home_page": "https://projects.om-office.de/frans/minimon.git",
"name": "minimon",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0.0",
"maintainer_email": "",
"keywords": "",
"author": "Frans F\u00fcrst",
"author_email": "frans.fuerst@protonmail.com",
"download_url": "https://files.pythonhosted.org/packages/30/32/8e5bde5cb93a79368d178c8b92fec69430e5c7e55dc6485a8ec7ab1d2793/minimon-0.1.7.tar.gz",
"platform": null,
"description": "# Minimon\n\n**minimon** is a 'minimal' (as in minimal music) IT monitoring tool for the command line.\n\nCompared to lots of other IT monitoring solutions it has the following main attributes:\n\n- It follows a 'configuration as application' approach, i.e. instead of configuring your monitoring\n via UI you will 'write' your whole executable application yourself!\n (see example below for clarification)\n- It's ultra-flexible by being more an 'automation with functional pipes' framework letting\n you do anything you can automate rather than a configurable application\n- It's _minimal_ also in terms of a hobby project. Don't expect something which competes with\n Checkmk, Prometheus, etc.\n- Since you have to implement / modify the main executable using plain Python (in contrast to\n configuring some black box application), you might get into Python programming rather quickly as\n a side effect.\n\n\nThere are some technical properties and maxims you might be interested in as well:\n\n- `textual` / `rich` based\n- Heavy use of asynchronous programming\n- Functional approaches wherever possible\n- `asyncssh` instead of `paramiko`\n\n\n## Installation\n\nWhile you can just clone and use minimon, the intended way to use it is to install it from PyPI.org\nor run it from inside a virtual environment.\n\nInstall it locally using `pip`:\n\n```sh\n[<PYTHON> -m] pip[3] install [--user] [--upgrade] minimon\n```\n\nCurrently you need at least Python **v3.10+** installed in order to run **minimon**. In case your\nsystem provides older versions only, consider using `pyenv` to install any other version next\nto your system-Python.\n\n\n## Example\n\nThe following snippet is taken from a recent **minimon** installation folder, e.g.\n`~/.local/lib/python3.11/site-packages/minimon/sites/mvm.py` and shows a poorly minimalistic but\nworking example of a fully functional **minimon** site:\n\n```python\nfrom minimon import *\nfrom minimon.plugins import df, ps\n\nwith Monitor(\"MVM\"):\n\n @view((\"host\", [Host(\"localhost\")]))\n async def local_resources(host: Host) -> AInsights:\n \"\"\"This async generator will be invoked by the above `view` and run continuously to\n gather and yield monitoring data\"\"\"\n async for insight in Bundler(\n ps=ps.generate(host) | ps.parse() | ps.check(),\n df=df.generate(host) | df.parse() | df.check(),\n ):\n yield insight\n```\n\nCreate/copy your own file to test and modify:\n\n```sh\nmkdir minimon-sites 130 \u21b5\ncp ~/.local/lib/python3.11/site-packages/minimon/sites/mvm.py minimon-sites\nchmod +x minimon-sites/mvm.py\n```\n\nStart it by executing\n```\nminimon-sites/mvm.py\n```\n\n\n## Why (do I do this?)\n\n- async\n- functional\n- testability\n- bullet proof\n\n\n## Todo\n\n### Core / enabler:\n- [ ] Fix: CTRL-C hang due to non terminated tasks\n- [ ] Read ssh passwords once on startup\n\n- [x] Provide a way to use data propagating through functions by different consumers\n- [x] Provide monadic (async) function chaining\n- [x] Support for endless processes (\"dmesg -w\")\n- [x] View: arbitrary number of parameters (0, 1, 2 for now)\n- [x] Host-config: parametrize check-pipe\n- [x] Fix: Styled log output, see https://stackoverflow.com/questions/77716718\n- [ ] Show Links (e.g. to monitoring)\n- [ ] Mature hierarchic error handling/propagation and restart management\n- [ ] Capture and persist metrics\n- [ ] Recognize (dis)appearance of found entities (df-mountpoints, network adapters, etc)\n- [ ] Support for remote APIs\n- [ ] Support for multi line scripts\n- [ ] Support for optional `su -c ..`\n- [ ] Recognize check state transitions -> notifications\n- [ ] Provide ways to interact\n- [ ] Improve logging: to file, log threads, log task context\n- [ ] Let core run in background\n- [ ] Check windows support\n- [ ] research: send mails\n\n\n### Visuals\n\n- [ ] visualize metrics\n\n\n### Reactions (automatic actions)\n\n- [ ] send build break notifications\n- [ ] run scripts open/close branches\n\n\n### Actions (user interaction)\n\n- [ ] rebuild failed jobs\n- [ ] kill/delete containers/volumes/tags/images\n- [ ] open/close branches\n- [ ] cleanup workspace(s)\n\n\n### SSH-Plugins:\n\n- [ ] disk space\n- [ ] ram\n- [ ] cpu usage over time\n- [ ] network usage per process\n- [ ] android: check battery\n- [ ] docker: number containers/images/volumes/networks/build cache\n- [ ] wrong permissions/ownerships `/home/jenkins -user root`\n- [ ] unused directories\n\n\n### API-Plugins:\n\n- [ ] docker: per container: cpu / ram / runtime\n- jenkins-jobs\n - [ ] job tree\n - [ ] warning about certain job results (sheriffing)\n - [ ] branch sheriffing state\n- [ ]job <=> containers association\n- [ ]nexus artifacts\n\n\n## Development & Contribution\n\n### Setup\n\nFor active development you need to have `poetry` and `pre-commit` installed\n\n```sh\npython3 -m pip install --upgrade --user poetry pre-commit\npoetry self add poetry-bumpversion\ngit clone git@projects.om-office.de:frans/minimon.git\ncd minimon\npre-commit install\n# if you need a specific version of Python inside your dev environment\npoetry env use ~/.pyenv/versions/3.10.4/bin/python3\npoetry install\n```\n\n\n### Workflow\n\n* Create/test/commit changes and check commits via `pre-commit`\n* after work is done locally:\n - bump version using `poetry version patch`\n - build and check a package\n```sh\npoetry build && \\\ntwine check dist/* &&\npython3 -m pip uninstall -y minimon && \\\npython3 -m pip install --user dist/minimon-$(grep -E \"^version.?=\" pyproject.toml | cut -d '\"' -f 2)-py3-none-any.whl\n```\n - check installed package\n - publish the new package `poetry publish --build`\n - commit new version && push\n\n\n## License\n\nFor all code contained in this repository the rules of GPLv3 apply unless\notherwise noted. That means that you can do what you want with the source\ncode as long as you make the files with their original copyright notice\nand all modifications available.\n\nSee [GNU / GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html) for details.\n\nThis project is not free for machine learning. If you're using any content\nof this repository to train any sort of machine learned model (e.g. LLMs),\nyou agree to make the whole model trained with this repository and all data\nneeded to train (i.e. reproduce) the model publicly and freely available\n(i.e. free of charge and with no obligation to register to any service) and\nmake sure to inform the author (me, frans.fuerst@protonmail.com) via email\nhow to get and use that model and any sources needed to train it.\n\n\n## Good to know\n\n### Gather some information\n\n- `free -b`\n- `df`\n- `dmesg -w`\n- `logcat`\n- `docker image list -aq | uniq | wc`\n- `docker container list -aq | wq`\n- https://www.baeldung.com/linux/get-cpu-usage\n- `vmstat -n 5`\n- `ss --numeric --resolve --processes --info`\n\n### `sshd` for Android\n\n- SimpleSSH\n- `host <IP>` -> hostname\n- `scp -P2222 ~/.ssh/id_ed25519.pub <HOST>:authorized_keys`\n- `ssh -p2222 <HOST> \"su -c 'dmesg -w'\"`\n- `ssh -p2222 <HOST> \"su -c 'df'\"`\n- `ssh -p2222 <HOST> \"su -c 'top'\"`\n- `ssh -p2222 <HOST> \"su -c 'dumpsys battery'\"`\n",
"bugtrack_url": null,
"license": "",
"summary": "minimon",
"version": "0.1.7",
"project_urls": {
"Homepage": "https://projects.om-office.de/frans/minimon.git",
"Repository": "https://projects.om-office.de/frans/minimon.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b6a13d313874c4a8c749406577ee0d8e73dce9cc5096fd3fba340409def8ec9c",
"md5": "6cdfa43530034b3229b6109e285d7e48",
"sha256": "3644e5ef1ac4c7f44028fe483d17243fefa84f8198ce5663908801689ab770a0"
},
"downloads": -1,
"filename": "minimon-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6cdfa43530034b3229b6109e285d7e48",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0.0",
"size": 39264,
"upload_time": "2023-12-26T12:28:42",
"upload_time_iso_8601": "2023-12-26T12:28:42.782577Z",
"url": "https://files.pythonhosted.org/packages/b6/a1/3d313874c4a8c749406577ee0d8e73dce9cc5096fd3fba340409def8ec9c/minimon-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "30328e5bde5cb93a79368d178c8b92fec69430e5c7e55dc6485a8ec7ab1d2793",
"md5": "622b8a854ad24be42594aa9bccd8249e",
"sha256": "150c18a9eddef22194d25b3bd81a5d68628a50bd5fa6370b1a271f64b39926ac"
},
"downloads": -1,
"filename": "minimon-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "622b8a854ad24be42594aa9bccd8249e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0.0",
"size": 31834,
"upload_time": "2023-12-26T12:28:44",
"upload_time_iso_8601": "2023-12-26T12:28:44.949452Z",
"url": "https://files.pythonhosted.org/packages/30/32/8e5bde5cb93a79368d178c8b92fec69430e5c7e55dc6485a8ec7ab1d2793/minimon-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-26 12:28:44",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "minimon"
}
JSON