[core] Add opt-in swap accounting to memory monitor and scheduler

[preneond]

Why

On bare-metal nodes with significant swap configured, Ray's OOM monitor kills tasks prematurely. The monitor computes its threshold purely from RAM, so when RAM approaches the threshold Ray starts killing workers — even though the kernel would have handled the overflow via swap without any issue. The Linux OOM killer only fires when both RAM and swap are exhausted; Ray's monitor was firing much earlier, on RAM alone.

Users who deliberately provision swap as overflow capacity get no benefit from it — Ray overrides the kernel's judgment before swap is ever meaningfully used.

The same mismatch affects the scheduler (node memory resource excludes swap) and the dashboard Node Memory graph (shows RAM-only total).

What

Adds a single opt-in flag RAY_count_swap_in_memory_monitor (env var) / count_swap_in_memory_monitor (RayConfig), default false. When enabled, swap is folded into:

1. C++ memory monitor — GetLinuxMemoryBytes reads SwapTotal/SwapFree from /proc/meminfo; GetCGroupMemoryBytes uses cgroup v1 memory.memsw.* (RAM+swap combined) or cgroup v2 memory.swap.{max,current} (swap-only, added on top of memory.{max,current}).
2. Node memory resource (resource_and_label_spec.py) — swap total is included in the auto-computed memory capacity seen by the scheduler and ray status.
3. Dashboard Node Memory graph (reporter_agent.py) — _get_cgroup_aware_swap() adds cgroup-scoped swap so the graph matches what the OOM killer sees in both bare-metal and containerized deployments.

All three sites are guarded by the same flag. Flag-off is the existing behavior — no scheduling or OOM-killer change for existing deployments.

Design notes

• Module-level vs per-call read: resource_and_label_spec.py reads the env var once at import time (consistent with how RayConfig is consumed at node start); reporter_agent.py re-reads on every poll tick so a hot-restart can pick up the change without rebuilding.
• cgroup v1 memsw fallback: If memory.memsw.limit_in_bytes is absent (kernel built without CONFIG_MEMCG_SWAP), code falls back silently to the existing RAM-only path.
• cgroup v2 unlimited swap: memory.swap.max can contain the string "max" (unlimited). The patch guards against std::stoll on that sentinel by checking std::all_of(..., ::isdigit) before parsing.
• Dashboard cgroup-scoped swap: _get_cgroup_aware_swap() reads cgroup v2 memory.swap.{max,current} or cgroup v1 memory.memsw.* directly, capping with host psutil values, so the dashboard total matches the C++ OOM killer's view inside containers.

Test plan

• Python unit tests — 3 new parametrized cases in python/ray/tests/unit/test_resource_and_label_spec.py: swap-enabled inflates memory resource, swap-disabled does not, explicit --memory bypasses swap regardless of flag.
• C++ unit tests — 8 new gtests in src/ray/common/tests/memory_monitor_utils_test.cc: Linux meminfo fold, swap ignored when flag off, no-swap host (missing SwapTotal lines), cgroup v2 swap added, cgroup v2 swap ignored when flag off, cgroup v2 unlimited swap not added, cgroup v1 memsw added to total/used, cgroup v1 memsw ignored when flag off.
• Manual smoke test: RAY_count_swap_in_memory_monitor=1 ray start --head && ray status — Node Memory should reflect RAM + swap.

Files changed

File	Change
src/ray/common/ray_config_def.h	New count_swap_in_memory_monitor bool flag
src/ray/common/memory_monitor_utils.h	cgroup memsw/swap path constants; FRIEND_TEST declarations
src/ray/common/memory_monitor_utils.cc	Swap accounting in GetCGroupMemoryBytes and GetLinuxMemoryBytes
src/ray/common/memory_monitor_test_fixture.h/cc	MockProcMeminfo, MockCgroupv2Swap, MockCgroupv1Memsw test helpers
src/ray/common/tests/memory_monitor_utils_test.cc	8 new C++ tests (incl. cgroup v1 memsw coverage)
python/ray/_private/resource_and_label_spec.py	Fold swap into auto-computed node memory resource
python/ray/dashboard/modules/reporter/reporter_agent.py	Cgroup-scoped swap in dashboard memory reporting via _get_cgroup_aware_swap()
python/ray/tests/unit/test_resource_and_label_spec.py	3 new Python tests

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces an opt-in configuration (RAY_count_swap_in_memory_monitor) to fold swap space into Ray's memory monitoring, node resource calculations, and dashboard metrics across both C++ and Python components. The review feedback highlights critical robustness improvements, specifically recommending exception handling when parsing memory.swap.max in C++ to prevent crashes on extremely large values, and wrapping psutil.swap_memory() calls in Python with try-except blocks to avoid failures in restricted or containerized environments.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit da2364f. Configure here.}