debugger-help 4.2.3

debugger.help VPS Agent — Deep system monitoring for logs, GPU, PM2, Docker, and more

debugger-help

Deep VPS monitoring agent for debugger.help. Captures PM2, GPU metrics, Docker containers, system health, and streams everything to your dashboard in real time.

Install

python3 -m pip install --upgrade debugger-help

With GPU monitoring:

python3 -m pip install --upgrade debugger-help[gpu]

With everything:

python3 -m pip install --upgrade debugger-help[all]

Quick Start

# 1) Install the Python package
python3 -m pip install --upgrade debugger-help

# 2) Add your project credentials
export DEBUGGER_API_KEY="your-api-key"
export DEBUGGER_INGEST_URL="your-ingest-url"

# 3) Start the agent
debugger-agent

Do not use placeholder commands like git+https://github.com/YOUR_ORG/... — install from PyPI with debugger-help.

Or keep it running with PM2:

pm2 start "debugger-agent" --name debugger-agent
pm2 save

Important naming

• debugger-help = the Python package you install with pip
• debugger-agent = the CLI command that package installs
• pip install debugger-agent will fail because there is no separate package with that name
• placeholder GitHub commands like git+https://github.com/YOUR_ORG/... are not real install commands

What it captures

• PM2 process states, restart counts, logs, error logs
• GPU: VRAM per-process, temperature, power, utilization, clock speeds, throttle reasons, ECC errors
• CPU: per-core usage, load average, frequency, context switches
• Memory: RAM, swap, shared, buffers, cached
• Disk: usage per mount, I/O rates, inode usage
• Network: per-interface stats, TCP connection states, open ports, DNS resolution
• Processes: top CPU/memory consumers, zombies, open file descriptors
• Docker containers: status, CPU, memory, restart counts
• Systemd: failed units
• SSL certificates: expiry checks
• System logs: dmesg, OOM kills, journalctl errors
• File watchers: syslog, PM2 logs, custom log files

Resource Usage

The agent is designed to be as lightweight as possible:

Resource	Typical Usage	Notes
RAM	~20–30 MB	Pure Python with psutil + requests
CPU	<1%	Polls every 10s by default, minimal processing
VRAM	0 MB	Reads GPU stats via pynvml driver queries — nothing is loaded onto the GPU
Disk	~5 MB installed	No local buffering or log storage
Network	~2–5 KB/s	Small JSON payloads sent every collection interval

The agent never interferes with your workloads. GPU monitoring uses NVIDIA's management library (pynvml) which queries the driver directly — no CUDA contexts are created, no VRAM is allocated.

Environment Variables

Variable	Required	Description
DEBUGGER_API_KEY	Yes	Your debugger.help API key
DEBUGGER_INGEST_URL	Yes	Your ingest endpoint URL
DEBUGGER_SOURCE	No	Source name (default: vps-{hostname})
DEBUGGER_INTERVAL	No	Collection interval in seconds (default: 10)
DEBUGGER_WATCH_LOGS	No	Comma-separated extra log file paths
DEBUGGER_SSL_DOMAINS	No	Comma-separated domains for SSL checks

FAQ

Will it slow down my GPU workloads? No. The agent uses zero VRAM and creates no CUDA contexts. It reads metrics through NVIDIA's management API, which is the same interface nvidia-smi uses.

Can I run it alongside my ML training / inference? Yes. It's completely passive — it only reads system stats. Many users run it on the same machines serving Flux, SDXL, and other heavy models without any impact.

What happens if the ingest endpoint is unreachable? The agent silently skips the send and retries on the next interval. No data is buffered to disk, so there's no risk of filling up storage.

Does it need root? No. Standard user permissions are sufficient for most metrics. Some system log files (like /var/log/syslog) may require adding your user to the appropriate group (e.g., adm).

Can I adjust the collection interval? Yes. Set DEBUGGER_INTERVAL to any number of seconds. Lower values give more granularity but slightly increase network usage.

License

MIT