Monitoring API

Simple Flask-based REST API that reports the host's CPU, memory, and disk usage. It exposes a single endpoint that returns JSON metrics and is intended to be run as a local service on port 3003.

License: MIT by AI Computer, LLC (see LICENSE).

Features

• Endpoint: GET http://127.0.0.1:3003/metrics
• Returns CPU percent, memory usage, disk usage, and a UTC timestamp
• Lightweight: Python + Flask + psutil
• Puppet module provided to install and manage as a systemd service

API

• Method: GET
• URL: /api/healthcheck
• Example response:

• Method: GET
• URL: /api/metrics
• Example response:

{
  "cpu_percent": 12.5,
  "memory": {
    "total_mb": 7982,
    "used_mb": 3241,
    "available_mb": 4567,
    "percent_used": 40.6
  },
  "disk": {
    "total_gb": 477,
    "used_gb": 210,
    "free_gb": 267,
    "percent_used": 44.0
  },
  "timestamp": "2025-12-16T14:23:01Z"
}

Quick start (manual)

1. Create a virtual environment and install dependencies

python3 -m venv venv
source venv/bin/activate
pip3 install -r requirements.txt
pip3 install -r requirements-dev.txt   # for tests & coverage

2. Run the service locally (port 3003)

python3 app.py

3. Query the endpoint

curl http://127.0.0.1:3003/metrics

Docker Build the image

docker build -t monitoring-api:latest .

Run on Linux with host metrics

• To make the container report the host machine's CPU/memory/disk stats and use correct networking, run with host PID and host network namespaces, and mount the host root read-only. The app supports DISK_MOUNT to point at the mounted host root for disk usage.

docker run --rm \
  --name monitoring-api \
  --pid=host \
  --network=host \
  -v /:/host:ro \
  -e DISK_MOUNT=/host \
  monitoring-api:latest

• Query (Linux):

curl http://127.0.0.1:3003/metrics

Notes for Docker Desktop (macOS/Windows)

• --pid=host and --network=host behave differently or are unsupported. In Docker Desktop, the container runs inside a lightweight VM, so the metrics will reflect that VM/container, not your macOS/Windows host.
• You can still run the service and access it via a published port:

docker run --rm \
  --name monitoring-api \
  -p 3003:3003 \
  monitoring-api:latest

• Query:

curl http://127.0.0.1:3003/metrics

Makefile helpers This repo provides a simple Makefile for local development:

# Create virtualenv
make venv

# Install runtime dependencies into venv
make install

# Run the application (uses venv)
make run

# Remove the virtualenv
make clean

Testing & coverage

1. Run unit tests with coverage locally

pytest --cov=app --cov-report=term-missing

2. Coverage gate in CI

• GitHub Actions workflow runs on pushes and PRs, testing Python 3.10–3.12.
• The job fails if line coverage for app drops below 80%.

3. What is covered

• Core function get_metrics and the /metrics Flask endpoint are tested with psutil mocked.

Install as a systemd service via Puppet This repo includes a complete Puppet module that installs and manages the Monitoring API as a systemd service named monitoring-api listening on port 3003.

Tested assumptions

• Target OS: modern Debian/Ubuntu-like with systemd
• Python 3 available as python3, pip3

Repo layout for Puppet

puppet/
  apply.pp                         # example manifest that includes monitoring_api
  modules/
    monitoring_api/
      manifests/
        init.pp                    # class monitoring_api
      files/
        monitoring-api.service     # systemd unit
        app.py                     # application (copied to /opt/monitoring-api)
        requirements.txt           # runtime dependencies
        version.py                 # app version file

Quick apply (local)

1. Ensure Puppet is installed and you have root privileges.

2. From the repo root, apply the module directly using the provided modulepath and example manifest:

sudo puppet apply \
  --modulepath puppet/modules \
  puppet/apply.pp

Alternative (inline):

sudo puppet apply --modulepath puppet/modules -e 'include monitoring_api'

What the module does

• Installs required packages (python3, python3-venv, python3-pip)
• Creates /opt/monitoring-api and a virtualenv /opt/monitoring-api/venv
• Deploys app.py, version.py, and requirements.txt
• Installs Python dependencies into the venv
• Installs the systemd unit /etc/systemd/system/monitoring-api.service
• Reloads systemd, enables, and starts the service

Verify it works

systemctl status monitoring-api --no-pager
sudo journalctl -u monitoring-api -n 50 --no-pager
curl -s http://127.0.0.1:3003/api/healthcheck
curl -s http://127.0.0.1:3003/api/metrics | jq .

Manage the service

• Start: sudo systemctl start monitoring-api
• Stop: sudo systemctl stop monitoring-api
• Restart: sudo systemctl restart monitoring-api
• Logs (follow): sudo journalctl -u monitoring-api -f

Uninstall (ensure => absent)

sudo puppet apply --modulepath puppet/modules -e "class { 'monitoring_api': ensure => 'absent' }"

Security notes

• The service listens on 0.0.0.0:3003. If this should be local-only, change the Flask host to 127.0.0.1 in app.py and restart the service.
• Consider firewalling port 3003 if exposing externally is not desired.

License MIT License © 2025 AI Computer, LLC. See LICENSE.