Heartbeat memory fields
When codescout runs with --debug, the periodic heartbeat tracing event now
includes per-instance memory snapshots taken from /proc/self/status:
heartbeat instance=6719 uptime_secs=30 active_projects=1 lsp_servers=[]
vm_size_kb=4911904 vm_rss_kb=47868 vm_data_kb=462344 vm_peak_kb=4912028
| Field | Source | What it tells you |
|---|---|---|
vm_size_kb | VmSize | Total virtual address space (includes jemalloc reservations). |
vm_rss_kb | VmRSS | Resident pages — the truthful “how much physical memory is this using right now”. |
vm_data_kb | VmData | Data + heap + stack pages. Grows with live allocations. |
vm_peak_kb | VmPeak | High-water mark for VmSize over the process lifetime. |
When to look
Useful when correlating long-running instance behaviour against per-project
tool call history (~/.codescout/usage.db and <project>/.codescout/usage.db).
The use case driving this addition is the open OOM investigation in
docs/issues/memory-leak-x-session-freeze.md: the kernel’s OOM dump only
captures the moment of death; the heartbeat captures the trajectory.
Platform notes
Linux only. On macOS/Windows the underlying /proc/self/status read fails
silently and all four fields log as 0; heartbeat continues regardless.
Cost
A read_to_string("/proc/self/status") plus a line-by-line parse. Runs once
every 30 seconds. Negligible.