[dashboard] Add py-spy --idle and --subprocesses flags to profiling endpoints

[marwan116]

Description

The dashboard profiling endpoints run py-spy — py-spy record for the CPU Flame Graph (/task/cpu_profile, /worker/cpu_profile) and py-spy dump for the Stack Trace (/task/traceback, /worker/traceback) — but only ever exposed the native flag. This PR plumbs two more py-spy flags through the same paths (query param → request proto field → reporter agent handler → CpuProfilingManager):

• idle=1 → py-spy record --idle (CPU Flame Graph). py-spy record samples only on-CPU (runnable) threads by default, so a worker blocked on a lock, I/O, or a CUDA sync shows up as near-idle and the flame graph is empty/misleading exactly when you need it most. --idle additionally captures off-CPU / sleeping threads, surfacing where a stalled worker is actually parked.
• subprocesses=1 → py-spy --subprocesses (both CPU Flame Graph and Stack Trace). A Ray worker is normally a single process, but many workloads fork children that do the real work — PyTorch DataLoader(num_workers>0), multiprocessing pools, or multiproc inference backends (e.g. vLLM tensor-parallel workers). --subprocesses follows the worker's process tree so activity in those children appears in the profile / stack dump instead of being invisible.

Why idle is record-only but subprocesses covers both paths: py-spy dump already snapshots all threads (including off-CPU / blocked ones), so --idle is only meaningful for record. --subprocesses, however, is a real capability gap on the dump path — without it, child stacks can't be captured via the Stack Trace button — so it is plumbed through trace_dump as well.

All flags default off and, unlike --native (which Ray restricts to Linux), work on all platforms, so none are platform-gated.

Related issues

N/A

Additional information

• Commits (stacked): (1) --idle on cpu_profile, (2) --subprocesses on cpu_profile, (3) --subprocesses on the traceback endpoints.
• Docs: all flags are documented in the Dashboard profiling guide (optimize-performance.rst) — append &idle=1 and/or &subprocesses=1 to the relevant request URL.
• Tests: test_profile_manager.py asserts each flag is appended to the constructed py-spy command iff requested (and absent by default), for both cpu_profile (record) and trace_dump (dump).
• Caveat (subprocesses): py-spy discovers child processes by periodically scanning the process tree, so very short-lived subprocesses may be missed; persistent workers (DataLoader, vLLM) are captured reliably.
• The generated reporter_pb2 bindings are gitignored and regenerated in CI, where the agent/head code paths and these tests run.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request adds support for the --idle (to include off-CPU/sleeping threads) and --subprocesses (to profile child processes) flags in the CPU profiling feature using py-spy. It updates the protobuf definitions, the dashboard reporter agent and head, the profiling manager, the documentation, and adds corresponding unit tests. There are no review comments, so I have no feedback to provide.

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.

[dstrodtman]

stamp for docs

[kshanmol]

LGTM, thanks for this improvement!