Package: python-monitoring-agent
Python Monitoring AgentPython Monitoring Agent (PMA)is a simple, lightweight, and modular monitoring agent.PMA serves as a standalone metrics exporter. It requires a database (influxdb) and a frontend tool (such as Grafana) to properly visualize data from influxdb.FeaturesSwap Information: App retrieves information about the swap memory usage, including total swap space, used swap space, free swap space. On frontend side, those are also calculated into SWAP utilization percentageRAM Information: App provides insights into RAM usage, including total RAM, used RAM, free RAM, cached RAM, buffers. On frontend side, those are also calculated into RAM utilization percentageCPU Information: App gathers CPU-related details such as user CPU time, system CPU time, idle CPU time, I/O wait time, current CPU frequency, maximum CPU frequency, minimum CPU frequency, CPU load averages (1m, 5m, 15m), CPU utilization percentage, CPU temperature, and the number of processors.Disk Information: App provides disks and filesystems information such as block device name, mounted filesystem, space used, space avaliable and space total. On frontend side, those are also calculated into filesystem utilization percentageNetwork InformationApp gathers network interface related metrics like bytes/packets sent/retrived, errors on interfaces and dropped packets. On frontend side, those are also calculated into network utilization over time (Bytes per second)Exception Handling and Logging: App encapsulates each value retrieval in a try-except block. If an exception occurs, the value is assigned asNone, and the exception is passed to alogginginstance, allowing for better error tracking and handling.UsageCurrently, there are two ways to use this software:As a Docker container (recommended for Linux)As a Python package (requires Python 3.6 or higher)Note:Docker usage is recommended on Linux but shouldn't be used on MacOS or Windows! Docker desktop for MacOS and Windows is essentially a Linux virtual machine, so metrics collected from Docker desktop with PMA would be meaningless. For these two systems, using the Python native version is recommended.Docker UsageAgent Only:Copy the.env.distfile to.env.Populate the.envfile with the appropriate values (only those starting with "AGENT" need to be modified).Set the docker-compose profile:export COMPOSE_PROFILE=agent-only.Build the agent image:docker compose build.Start the agent image:docker compose up -d.Full Stack:Copy the.env.distfile to.env.Populate the.envfile with the proper values.Set the docker-compose profile:export COMPOSE_PROFILE=full.Start the InfluxDB container:docker compose up -d influxdb.Access the InfluxDB WebUI (default:http://127.0.0.1:8086).Create an API token from the "Load Data" > "API Tokens" menu.Copy and paste the API token into the.envfile.Build the agent container:docker compose build.Start the other containers:docker compose up -d.Open the Grafana WebUI (default:http://127.0.0.1:3000).From the "Administration" > "Data Sources" menu, create a new InfluxDB datasource:Set the query language to Flux.Add the InfluxDB URL. Both Grafana and InfluxDB are inside the docker-compose default network, so usehttp://influxdb:8086as the URL (modify accordingly if you changed the service name in docker-compose.yml).Disable basic authentication.Fill in the default bucket and default organization. This is important if you want to use the provided dashboard without modification.Fill in the API token with your token.From the "Dashboards" menu, select "New" > "Import" and drag and drop thedocker/grafana/Python-monitoring-agent.jsonfile.Open your dashboard and select your host.Python Package UsageAgent Only:Install the Python package:pip install ./docker/agent.Start the app withpmafrom the terminal.An empty configuration file will be created in$XDG_CONFIG_HOMEdirectory. If$XDG_CONFIG_HOMEis not set or you are on Windows or macOS,$HOME/.configwill be used as the base directory.Edit the configuration file at$XDG_CONFIG_HOME/python-monitoring-agent/config.yamlor$HOME/.config/python-monitoring-agent/config.yamland replace the default values with your own.Start the app withpma. If you want to start the app in the background without binding it to your terminal, usenohup pma &(works on both macOS and Linux).Configuration explainedConfig OptionExplanationAGENT_INFLUX_URLThe URL of the InfluxDB instance to connect to.AGENT_INFLUX_BUCKETThe name of the InfluxDB bucket to use.AGENT_INFLUX_ORGThe name of the InfluxDB organization to use.AGENT_INFLUX_TOKENThe API token for accessing InfluxDB.AGENT_HOSTNAMEThe hostname of the agent.AGENT_POOLING_RATEThe rate at which the agent performs pooling.AGENT_VERBOSITYThe level of verbosity for logging.AGENT_DOCKERDocker specific option, needs to exist as environment if docker is used (Can be set to anything, like "True")DOCKER_INFLUXDB_INIT_USERNAMEInitial WebUI username for InfluxDB.DOCKER_INFLUXDB_INIT_PASSWORDInitial WebUI password for InfluxDB.DOCKER_INFLUXDB_INIT_ORGInitial organization name for InfluxDB.DOCKER_INFLUXDB_INIT_BUCKETInitial bucket name for InfluxDB.DOCKER_INFLUXDB_INIT_MODEInitial Docker setup mode for InfluxDB.TODOAdd sensors metricsAdd more metrics overallCreate CI/CD Pipeline that would be building and publishing Docker images and Python package on releasesThink of a way of allowing new modules to be added easilyAdd cron/systemd timers modeAdd systemd unit fileContributionContributions Welcome!We welcome contributions from anyone interested in improving our project. If you have ideas, bug fixes, or new features to propose, we encourage you to create pull requests. Together, we can make this project even better!Feel free to explore the codebase, find areas where you can contribute, and submit your pull requests. We appreciate your support and look forward to collaborating with you!