philiprehberger-server-monitor 0.4.0

System metrics collector for CPU, memory, disk, and network

philiprehberger-server-monitor

System metrics collector for CPU, memory, disk, and network.

Installation

pip install philiprehberger-server-monitor

Usage

Single Snapshot

from philiprehberger_server_monitor import Monitor

monitor = Monitor()
snap = monitor.snapshot()
print(f"CPU: {snap.cpu.percent}%")
print(f"Memory: {snap.memory.used_gb:.1f}/{snap.memory.total_gb:.1f} GB")
print(f"Disk: {snap.disk['/'].percent}%")

# Export snapshot
data = snap.to_dict()

Continuous Monitoring with Alerts

from philiprehberger_server_monitor import Monitor, Alert

monitor = Monitor()
monitor.watch(
    interval=5.0,
    on_snapshot=lambda s: print(f"CPU: {s.cpu.percent}%"),
    alerts=[
        Alert(metric="cpu.percent", threshold=90, callback=lambda m, v, t: print(f"HIGH CPU: {v}%")),
        Alert(metric="memory.percent", threshold=85, callback=lambda m, v, t: print(f"HIGH MEM: {v}%")),
    ],
)

Trend Tracking

from philiprehberger_server_monitor import Monitor

monitor = Monitor()

# Start recording snapshots every 5 seconds (keeps last 720)
monitor.start_recording(interval=5.0, max_snapshots=720)

# Later, analyze trends over the last 5 minutes
trend = monitor.get_trend("cpu.percent", window_seconds=300)
print(f"CPU slope: {trend.slope:.4f}%/s")
print(f"CPU went from {trend.start_value}% to {trend.end_value}%")

# Stop recording
monitor.stop_recording()

Trailing-window averages

from philiprehberger_server_monitor import Monitor

monitor = Monitor()
monitor.start_recording(interval=5.0)
# ... time passes ...

# Average CPU/memory % across snapshots in the trailing window (default 60s)
print(f"Avg CPU (last 60s): {monitor.average_cpu():.1f}%")
print(f"Avg memory (last 5 min): {monitor.average_memory(window_seconds=300):.1f}%")

Persisting Recorded Snapshots

monitor = Monitor()
monitor.start_recording(interval=5.0)
# ... time passes ...
monitor.export_json("metrics.json")

# Or grab a defensive copy of the buffer for in-process analysis
recent = monitor.snapshots()
print(f"Have {len(recent)} snapshots")

API

Function / Class	Description
Monitor	System metrics monitor with snapshot(), watch(), stop(), and trend tracking methods
Snapshot	A point-in-time system metrics snapshot with cpu, memory, disk, network fields
CpuInfo	CPU metrics (percent, count, count_logical, per_cpu, freq_mhz)
MemoryInfo	Memory metrics (total, available, used, percent) with GB properties
DiskInfo	Disk metrics for a single mount point (total, used, free, percent)
NetworkInfo	Network metrics (bytes_sent, bytes_recv, packets_sent, packets_recv)
Alert(metric, threshold, callback)	Threshold-based alert configuration for continuous monitoring
Trend	Trend analysis result with metric, start_value, end_value, slope, duration_seconds
monitor.start_recording(interval, max_snapshots)	Start background snapshot recording into a ring buffer
monitor.stop_recording()	Stop the recording thread
monitor.get_trend(metric, window_seconds)	Compute linear trend for a metric over recent snapshots
monitor.snapshots()	Return a copy of the recorded snapshot buffer
monitor.export_json(path)	Write recorded snapshots to a JSON file
monitor.average_cpu(window_seconds=60)	Mean CPU % across snapshots in the trailing window (0.0 if empty)
monitor.average_memory(window_seconds=60)	Mean memory % across snapshots in the trailing window (0.0 if empty)

Development

pip install -e .
python -m pytest tests/ -v

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT