Metadata-Version: 2.4
Name: debugger-help
Version: 4.2.3
Summary: debugger.help VPS Agent — Deep system monitoring for logs, GPU, PM2, Docker, and more
Author: debugger.help
License: MIT
Project-URL: Homepage, https://debugger.help
Project-URL: Repository, https://github.com/YourStudioPro/debuggerhelp
Keywords: debugger,monitoring,logging,gpu,vps,observability
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: psutil>=5.9.0
Requires-Dist: requests>=2.28.0
Provides-Extra: gpu
Requires-Dist: pynvml>=11.0.0; extra == "gpu"
Provides-Extra: docker
Requires-Dist: docker>=6.0.0; extra == "docker"
Provides-Extra: all
Requires-Dist: pynvml>=11.0.0; extra == "all"
Requires-Dist: docker>=6.0.0; extra == "all"

# debugger-help

Deep VPS monitoring agent for [debugger.help](https://debugger.help). Captures PM2, GPU metrics, Docker containers, system health, and streams everything to your dashboard in real time.

## Install

```bash
python3 -m pip install --upgrade debugger-help
```

With GPU monitoring:
```bash
python3 -m pip install --upgrade debugger-help[gpu]
```

With everything:
```bash
python3 -m pip install --upgrade debugger-help[all]
```

## Quick Start

```bash
# 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:
```bash
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
