Module proc_meta 

Shared Linux per-process metadata helpers used across every Linux backend.

GPU drivers tell us which PIDs are touching the GPU and how much VRAM they hold; the rest of a process’s identity lives in /proc. These helpers turn that into two columns the story feed leans on:

• CPU % (CpuTracker): a GPU at 3% with python pinning a CPU core is the classic dataloader-bound fingerprint — the GPU is starved, not idle.
• container identity (container_of): “the run is docker:1a2b3c4d5e6f” is what a cluster operator actually needs to find the offending pod.

Per the domain rules in CLAUDE.md every value is Option and absence is normal: a PID can exit between the GPU listing it and us reading /proc, /proc/<pid> may be a foreign user’s process we cannot read, and corrupt/racy reads must yield None, never a panic or a fabricated number. The parsers are split out as pure functions so they unit-test without a /proc at all.

Structs

CpuTracker

Tracks per-PID CPU time across ticks to turn the kernel’s cumulative counter into an instantaneous rate. A single /proc/<pid>/stat read only gives total ticks consumed since the process started; the rate is the delta between two reads over the wall time between them.

Functions

container_of

Container identity for a live PID by reading /proc/<pid>/cgroup. Any IO error (PID gone, foreign user, no procfs) reads as “host / unknown” → None; this never fails.

parse_cgroup

Parse a container runtime out of /proc/<pid>/cgroup content. Pure so it tests against captured cgroup strings — no /proc required.

parse_stat_ticks

Sum of utime + stime (fields 14 and 15, 1-indexed) from a /proc/<pid>/stat line.