# collectors/

One module per telemetry source. All collectors:

- Receive an `episode_id`, an output directory, and a shared `t_mono_origin_ns`.
- Write JSONL into `data/episodes/<episode_id>/telemetry-<name>.jsonl`.
- Stamp every row with the same `t_mono_ns` / `t_wall_ns` clock pair.
- Stamp every row with `source` and `available_in_deployment` (true/false).
- Exit cleanly on `SIGTERM` from the orchestrator.

| Module | Source | Vantage | Role |
|---|---|---|---|
| `proc_qemu.py` | host `/proc/<qemu_pid>/{stat,io,status,schedstat}` | outside guest | oracle |
| `qmp.py` | QEMU QMP `query-stats`, `query-blockstats`, netdev | outside guest | oracle |
| `perf_qemu.py` | `perf stat -p <qemu_pid>` | outside guest | oracle |
| `pcap.py` | `tcpdump -i br-malware`, bucketed | gateway-side | feature |
| `guest_agent.py` | virtio-serial reader, parses agent JSONL | inside guest | feature |

The in-guest agent itself (a small Python+psutil program that runs on the
guest and writes to `/dev/virtio-ports/cis490.guest.agent`) lives under
`vm/guest-agent/` because it is shipped *into* the guest at image-build time.

See [`docs/data-model.md`](../docs/data-model.md) for row schemas.