Not every memory failure has the same boundary
A process can fail allocation because of its workload limit even when the host appears to have spare memory. Conversely, a host-wide pressure event can affect workloads whose individual settings look reasonable. Distinguishing those boundaries prevents a misleading response such as adding host RAM to a workload still constrained by the same limit.
An application exception, an operating-system OOM kill and a deliberate service-manager stop are separate events. Begin with exit evidence and the kernel or supervisor timeline. Do not label every sudden restart as an OOM event simply because memory use was high earlier in the day.
Setup: identify the actual control group
Record the workload identity, runtime and cgroup version. On cgroup v2, /proc/PID/cgroup identifies a process's group; translate the live PID carefully because a restarted service has a new process. Read the relevant group's memory limit, current usage and event files with appropriate diagnostic access.
The kernel documents memory.high as a pressure boundary and memory.max as a hard limit, with distinct behavior. memory.events includes descendant events, while memory.events.local narrows the scope. Use counter changes over the incident interval; a historical nonzero value is not proof of a new kill.
Illustrative incident: an import reaches its service limit
An illustrative import worker runs alongside a web application. The worker loads an unexpectedly large input and restarts while the host's broad memory dashboard still looks acceptable. This is a teaching scenario, not a customer incident or a measured capacity benchmark.
Correlate the worker's process lifecycle with the cgroup event delta, configured limits and workload size. Ask whether the event occurred in this group or a descendant. Compare the successful small-input path with the failing input without copying private production records into an unrestricted test environment.
Troubleshooting: classify before changing capacity
| Observation | Evidence | Hypothesis to test |
|---|---|---|
| Workload restarts near a configured limit | Group usage, max and event delta | A group constraint may be the immediate boundary |
| Many services degrade together | Host memory and kernel timeline | Pressure may be broader than one application |
| Application reports allocation failure without a kill | Runtime logs and exit behavior | The runtime may have its own allocation limit |
| Parent event count increases | Local and descendant counters | Another workload in the hierarchy may be responsible |
Where available, inspect memory.stat to distinguish anonymous allocations, file-backed use and other categories. Do not equate a single runtime heap number with the complete group charge. The available counters and service-manager interfaces vary with kernel and distribution release.
Correct the allocation pattern or reviewed limit
Determine whether the workload is bounded as intended. Streaming input, reducing concurrent work or fixing retained objects can be more durable than repeatedly increasing a limit. These choices need application evidence; they are not universal tuning instructions for every language runtime.
If legitimate demand requires more capacity, review host headroom and neighboring workloads before changing the group limit. Use the service manager or orchestrator that owns the setting, so a manual change is not lost or contradicted later. Avoid disabling memory isolation as a general incident workaround.
Verification, service objective and handover
Repeat representative input sizes and concurrency in an approved environment. Confirm task completion, peak group usage, pressure behavior and absence of new OOM kills during the acceptance window. Verify that recovery does not cause duplicate imports or leave partially completed business work unaccounted for.
An example internal SLI is the fraction of eligible import jobs completed correctly within their processing deadline. Set the SLO from observed demand and business needs, then alert on both user impact and resource precursors. A contractual SLA is separate. The SOP should record group ownership, measurement scope, capacity approval, interrupted-work reconciliation and when to escalate to application or host engineering.
See Clouvenix server performance for help defining a reviewed operational scope.
Technical reference
Linux cgroup v2 memory interface, systemd resource controls. Reviewed 19 October 2026; select documentation matching the installed release.