What does resource.getrusage(resource.RUSAGE_SELF) report about a process?

### Accounting, not limiting `resource.getrlimit` tells you what your process is *allowed* to consume; `resource.getrusage` tells you what it *has* consumed. `resource.getrusage(resource.RUSAGE_SELF)` returns a `resource.struct_rusage` — a named tuple-like object of counters the kernel has been maintaining for this process since it started. It is a single, cheap syscall, always available on Unix, and needs no third-party profiler. ### The fields that carry real information * `ru_utime` and `ru_stime` — CPU seconds spent in user code and in the kernel on this process's behalf, as floats. They are summed across all threads, so a process with four busy threads can report four seconds of `ru_utime` per wall-clock second. * `ru_maxrss` — the **peak** resident set size reached so far: a high-water mark that never goes down, even after the memory is freed. It answers "how big did this ever get", not "how big is it now". * `ru_minflt` and `ru_majflt` — page faults served without and with disk I/O. A climbing major-fault count is the fingerprint of a process being swapped. * `ru_inblock` and `ru_oublock` — block input and output operations. * `ru_nvcsw` and `ru_nivcsw` — voluntary context switches (the process blocked on something) and involuntary ones (the scheduler preempted it). A high involuntary count means CPU contention. Several of these fields are simply zero on some platforms; the kernel fills in what it tracks, and Python passes the structure through unchanged. Check a value is non-zero on your target OS before building an alert on it. ### The portability trap in `ru_maxrss` The units of `ru_maxrss` are **not** the same everywhere. On Linux the value is in kilobytes; on macOS it is in bytes. The same code therefore reports a number a thousand times larger on one platform than on the other, and the classic bug is a memory dashboard that looks fine in CI on one OS and absurd in production on the other. Normalise explicitly at the point of measurement, keyed on `sys.platform`, and label the unit in whatever you emit. ### `RUSAGE_SELF` versus `RUSAGE_CHILDREN` `resource.RUSAGE_SELF` covers the calling process only — not its children, however many it has spawned. `resource.RUSAGE_CHILDREN` covers children that have **terminated and been waited for**; a child still running contributes nothing, and one that was never reaped contributes nothing either. For the children entry, `ru_maxrss` is the maximum over those children, not their sum, so it will never tell you the aggregate footprint of a worker pool. A parent that wants a true total has to collect a measurement inside each worker before it exits. ### How it compares with the alternatives `time.process_time` returns the same CPU-time concept with a cleaner interface and higher resolution, so for pure CPU timing it is the better call; `time.monotonic` gives wall clock, and the gap between wall clock and CPU time is exactly how much of a slow operation was spent waiting rather than computing. What `getrusage` adds over both is the memory high-water mark and the fault and context-switch counters, which no `time` function reports. For live memory rather than the peak, `tracemalloc` measures Python-level allocations, and the operating system's own per-process reporting measures the whole process. ### Using it well The useful pattern is a difference, not an absolute: capture the structure before and after a unit of work and subtract the CPU-time fields, because the raw values include everything since process start. `ru_maxrss` cannot be differenced meaningfully — it only ever rises — so treat it as a lifetime watermark, sampled at the end of a job or emitted periodically as a gauge. Logging `ru_utime`, `ru_stime` and `ru_maxrss` once per completed job, next to the soft limits read from `resource.getrlimit`, gives a cheap, dependency-free answer to "how close is this workload to the ceiling it was given" — which is the question the limits themselves cannot answer.