diff --git a/README.md b/README.md index af17896..1639dfd 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,81 @@ [![Pylint](https://github.com/systemswatch/processwatch/actions/workflows/pylint.yml/badge.svg)](https://github.com/systemswatch/processwatch/actions/workflows/pylint.yml) -# Process Watch -* License: (Apache 2.0), Copyright (C) 2024, Author Phil Chen + +# PROCESS WATCH +* License: (Apache 2.0), Copyright (C) 2025, Author Phil Chen * The author or owner of this repository is not liable for damages or losses arising from your use or inability to use the code. + +## DESCRIPTION +Process Watch monitors processes and workflows in your Linux system for anomalies or situations which when arise trigger predetermined actions you designate. + +This is useful for systems issues, automating troubleshooting, provisioning, scaling, and much more. + +## PREREQUISITES +Python 3.11 or higher + +## INSTALLATION + +### Install Process Watch on Ubuntu + +1. `gunzip -c process-watch.tar.gz | tar -xvf - ` +2. `mv process-watch /usr/local/` +3. `cd /usr/local/process-watch` +4. `pip install -r requirements.txt` +5. `/usr/local/process-watch/tools/config_tool.py` +6. `cd /usr/local/process-watch/systemd` +7. `sudo cp process_watch.service /etc/systemd/system/` +8. `sudo systemctl daemon-reload` +9. `sudo systemctl enable process_watch` +10. `sudo systemctl start process_watch` + +## CONFIGURATION + +Configuring Process Watch is done through a configuration tool located in the tools directory. The configuration tool will give you several options to create or manage configurations. + +1. `python3 /usr/local/process-watch/tools/config_tool.py` + +Config Tool Menu + +### Configure Process Profile Configuration + +Process profilers are the different functionalities Process Watch offers based on process utilization. Any time you make a new configuration via the configuration tool you must restart Process Watch by executing `sudo systemctl restart process_watch` for the new config to take effect. + +You can access the Process Profile Configuration menu from the main menu by choosing the option "Create a Process Profile Configuration". + +Configuration Creation Menu + +### Create General Process Profiler + +The General Process Profiler, will monitor the process you dictate at the interval you specify and write CPU, RSS memory usage, file descriptor, and thread count log entry in the logs directory under the naming convention `your-file-name-gen-profiler.log`. + +You can create a General Process Profiler via the Process Profile Configuration menu by choosing the option "Create General Process Profiler". + +See the following example below for configuration options: + +General Process Profiler Settings + +### Create Memory Process Profiler + +The Memory Process Profiler, will monitor the memory utilization for the process you dictate at the interval you specify and write a log entry when you exceed a memory threshold you define in the logs directory under the naming convention `your-file-name-mem-profiler.log`. Memory Process Profiler can also take action when the memory threshold is exceeded. We recommend you write a shell script for the wanted action or actions upon exceeding the memory threshold. + +You can create a Memory Process Profiler via the Process Profile Configuration Menu by choosing the option "Create Memory Process Profiler". + +See the following example below for configuration options: + +Memory Process Profiler Settings + +### Create File Descriptor Process Profiler + +The File Descriptor Process Profiler, will monitor the file descriptor utilization for the process you dictate at the interval you specify and write a log entry when you exceed a file descriptor threshold you define in the logs directory under the naming convention `your-file-name-fds-profiler.log`. File Descriptor Process Profiler can also take action when the file descriptor threshold is exceeded. We recommend you write a shell script for the wanted action or actions upon exceeding the file descriptor threshold. + +You can create a File Descriptor Process Profiler via the Process Profile Configuration Menu by choosing the option "Create File Descriptor Process Profiler". + +See the following example below for configuration options: + +Memory Process Profiler Settings + +### Quick Notes + +* Logs are stored in `/usr/local/process_watch/logs` +* Each profiler has its own log file. +* If you need to run Process Watch as a non-root user simply modify the systemd file swapping root for your user. +* If you need access to see the contents of individual Profiler Configuration files they are located at `/usr/local/process_watch/watch_list` under the configuration file name you provided upon creation. diff --git a/documentation/config-tool-menu.png b/documentation/config-tool-menu.png new file mode 100644 index 0000000..6d6d0f1 Binary files /dev/null and b/documentation/config-tool-menu.png differ diff --git a/documentation/configuration-creation-sub-menu.png b/documentation/configuration-creation-sub-menu.png new file mode 100644 index 0000000..eb86b17 Binary files /dev/null and b/documentation/configuration-creation-sub-menu.png differ diff --git a/documentation/configuration-creation.png b/documentation/configuration-creation.png new file mode 100644 index 0000000..60986bb Binary files /dev/null and b/documentation/configuration-creation.png differ diff --git a/documentation/general-process-profiler-settings.png b/documentation/general-process-profiler-settings.png new file mode 100644 index 0000000..5d8bef3 Binary files /dev/null and b/documentation/general-process-profiler-settings.png differ diff --git a/documentation/global-system-processess-profiler.settings.png b/documentation/global-system-processess-profiler.settings.png new file mode 100644 index 0000000..114db5f Binary files /dev/null and b/documentation/global-system-processess-profiler.settings.png differ diff --git a/documentation/memory-process-profiler-settings.png b/documentation/memory-process-profiler-settings.png new file mode 100644 index 0000000..f4c3e8c Binary files /dev/null and b/documentation/memory-process-profiler-settings.png differ diff --git a/documentation/thread-process-profiler-settings.png b/documentation/thread-process-profiler-settings.png new file mode 100644 index 0000000..0dcdfde Binary files /dev/null and b/documentation/thread-process-profiler-settings.png differ