# cloud/monitor — UDP Performance Monitor

A small Python utility for watching real-time UDP traffic across a fleet of endpoints. It's not a Node service — it's a standalone script used to measure packet loss and jitter on media-server endpoints, primarily as a diagnostic when multiplayer quality regresses.

**Location:** [cloud/monitor/](../../cloud/monitor).
**Language:** Python 3.7+ (standard library only — `asyncio`, `json`, `statistics`).
**Not a yarn workspace.**

## What it measures

```mermaid
flowchart LR
    CFG["config.json<br/>{ servers: [{ ip, port }, ...] }"]
    TOOL["media_mon.py<br/>(asyncio UDP listeners)"]
    STATS["per-endpoint stats:<br/>avg interval,<br/>jitter,<br/>min/max,<br/>sequence anomalies"]

    CFG --> TOOL
    TOOL -->|UDP listen| E1[media_server_next #1]
    TOOL -->|UDP listen| E2[media_server_next #2]
    TOOL -->|UDP listen| EN[... up to hundreds]
    TOOL --> STATS
```

Each UDP packet arriving at a listener is timestamped. The script computes inter-arrival intervals, standard deviation (jitter), and — when packets carry a 4-byte sequence number prefix — detects missing or out-of-order packets. After a configurable duration it prints per-endpoint stats.

## Typical use

```bash
# From cloud/monitor/
python media_mon.py --config config.json --duration 60
```

`config.json` (an example shape; the real one in the folder has the actual endpoint list):

```json
{
  "servers": [
    { "ip": "192.168.1.100", "port": 5000 },
    { "ip": "192.168.1.101", "port": 5001 }
  ]
}
```

## When to reach for it

- A player reports choppy audio or video → run `monitor` against the suspect media-server endpoints to see if the problem is packet loss vs. something higher in the stack.
- Before and after a mediasoup config change → compare jitter / loss deltas.
- Network troubleshooting between AWS regions.

## Why it's Python

It's single-purpose network diagnostic tooling. Python's `asyncio` makes it trivial to listen on hundreds of endpoints concurrently without a dependency tree, and it doesn't need to talk to any of the Node services directly.

## Further reading

- The media servers being monitored → [services/media-server.md](./media-server.md)
- Known performance investigations → [../debug_media_server_delay.md](../debug_media_server_delay.md)