From ba448bae1302394b904f535b572e601db1193fc7 Mon Sep 17 00:00:00 2001
From: anti <samuel@securejump.cl>
Date: Fri, 17 Apr 2026 13:17:23 -0400
Subject: [PATCH] docs: py-spy 0.4.1 lacks Python 3.14 support; wrapper aborts
 early

Root cause of 'No python processes found in process <pid>': py-spy needs
per-release ABI knowledge and 0.4.1 (latest PyPI) predates 3.14. Wrapper
now detects the interpreter and points users at pyinstrument/memray/cProfile.
---
 scripts/profile/pyspy-attach.sh | 16 +++++++++++++++-
 tests/perf/README.md            |  9 ++++++++-
 2 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/scripts/profile/pyspy-attach.sh b/scripts/profile/pyspy-attach.sh
index 5a61e42..cc01915 100755
--- a/scripts/profile/pyspy-attach.sh
+++ b/scripts/profile/pyspy-attach.sh
@@ -13,6 +13,20 @@ if [[ -z "${PID}" ]]; then
     exit 1
 fi
 
+PY_VER="$(python -c 'import sys; print(f"{sys.version_info[0]}.{sys.version_info[1]}")')"
+if [[ "${PY_VER}" == "3.14" ]] || [[ "${PY_VER}" > "3.14" ]]; then
+    cat >&2 <<EOF
+WARNING: py-spy 0.4.1 (latest on PyPI) does not yet support Python ${PY_VER}.
+Attaching will fail with "No python processes found in process <pid>".
+Use one of the other lenses for now:
+    DECNET_PROFILE_REQUESTS=true   # pyinstrument, per-request flamegraphs
+    scripts/profile/memray-api.sh  # memory allocation profiling
+    scripts/profile/cprofile-cli.sh <cmd>  # deterministic CLI profiling
+Track upstream: https://github.com/benfred/py-spy/releases
+EOF
+    exit 2
+fi
+
 echo "Attaching py-spy to PID ${PID} for ${DURATION}s -> ${OUT}"
-sudo py-spy record -o "${OUT}" -p "${PID}" -d "${DURATION}" --subprocesses
+sudo .venv/bin/py-spy record -o "${OUT}" -p "${PID}" -d "${DURATION}" --subprocesses
 echo "Wrote ${OUT}"
diff --git a/tests/perf/README.md b/tests/perf/README.md
index 38310c4..b5f7918 100644
--- a/tests/perf/README.md
+++ b/tests/perf/README.md
@@ -4,6 +4,13 @@ Five complementary lenses. Pick whichever answers the question you have.
 
 ## 1. Whole-process sampling — py-spy
 
+> **Note:** py-spy 0.4.1 (latest on PyPI as of 2026-04) does **not** yet support
+> Python 3.14, which DECNET currently runs on. Attaching fails with
+> *"No python processes found in process <pid>"* even when uvicorn is clearly
+> running. Use lenses 2–5 until upstream ships 3.14 support
+> (track https://github.com/benfred/py-spy/releases). The wrapper script aborts
+> with a clear message when it detects 3.14+.
+
 Attach to a running API and record a flamegraph for 30s. Requires `sudo`
 (Linux ptrace scope).
 
@@ -12,7 +19,7 @@ Attach to a running API and record a flamegraph for 30s. Requires `sudo`
 sudo py-spy record -o profile.svg -p <PID> -d 30 --subprocesses
 ```
 
-If py-spy "doesn't work", it is almost always one of:
+Other common failure modes (when py-spy *does* support your Python):
 - Attached to the Typer CLI PID, not the uvicorn worker PID (use `pgrep -f 'uvicorn decnet.web.api'`).
 - `kernel.yama.ptrace_scope=1` — run with `sudo` or `sudo sysctl kernel.yama.ptrace_scope=0`.
 - The API isn't actually running (a `--dry-run` deploy starts nothing).