docs(profiling-315): py3.15 dev tooling and CPython upgrade runbook - #19273
docs(profiling-315): py3.15 dev tooling and CPython upgrade runbook#19273vlad-scherbich wants to merge 8 commits into
Conversation
|
Codeowners resolved asResolved from the full PR diff against |
Circular import analysis
|
4b85b1d to
636fd80
Compare
e703ab0 to
e95f62f
Compare
636fd80 to
ba0a39e
Compare
b906b1e to
ba0e2bf
Compare
ba0a39e to
082c37a
Compare
Dependency direction analysis
|
082c37a to
6d9945a
Compare
50bf856 to
f29e0ea
Compare
6d9945a to
5059048
Compare
f29e0ea to
8b78ec5
Compare
There was a problem hiding this comment.
Pull request overview
Adds Python 3.15 profiling bring-up tooling and documentation to support the ongoing py3.15 profiling stack work: a standalone profiler compatibility verifier, a one-command profiling test runner, CPython 3.14→3.15 ABI change notes, and a maintainer runbook for bringing profiling up on new CPython minors.
Changes:
- Introduces
scripts/verify_profiler_compatibility.py(asyncio guard validation + real pprof sample collection + baseline compare) andscripts/run-profiling-tests(runner wiring compatibility checks + Riot profiling suites). - Adds py3.15 stack navigation/helpers under
scripts/py315-stack/(tracking, PR body generation, PR-number syncing, historical rebuild notes). - Adds/updates documentation for CPython 3.15 profiling bring-up (
docs/contributing-profiling-new-cpython.rst,docs/cpython-diffs/analysis_314_to_315.md) and links from contributor docs.
Reviewed changes
Copilot reviewed 57 out of 57 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/verify_profiler_compatibility.py | New Python script to validate asyncio profiling guards + collect/validate profiler samples and compare to stored baselines. |
| scripts/run-profiling-tests | New Bash runner to execute the compatibility script plus Riot profiling suites on a target Python. |
| scripts/py315-stack/TRACKING.md | Post-split tracking notes for remaining py3.15 parity follow-ups. |
| scripts/py315-stack/sync-pr-numbers.sh | Helper to sync PR numbers for stack navigation using gh. |
| scripts/py315-stack/rebuild-stack.sh | Historical script for rebuilding the older 14-PR stack chain. |
| scripts/py315-stack/PROFILING_STACK.md | Defines the live 5-PR profiling stack merge order and validation legs. |
| scripts/py315-stack/pr-numbers.env | Stores PR numbers for stack navigation tooling. |
| scripts/py315-stack/pr-bodies/VERSION-AUDIT-DRAFTS.md | Draft PR-body correction notes for version-claim audit. |
| scripts/py315-stack/pr-bodies/14-vlad-315-profiling-release-note.md | Generated PR body for historical stack layer 14 (release note). |
| scripts/py315-stack/pr-bodies/14-vlad-315-official-support.md | Generated PR body for historical stack layer 14 (official support). |
| scripts/py315-stack/pr-bodies/14-compare.url | Generated GitHub compare URL for historical stack layer 14. |
| scripts/py315-stack/pr-bodies/13-vlad-315-profiling-release-note.md | Generated PR body for historical stack layer 13 (release note). |
| scripts/py315-stack/pr-bodies/13-vlad-315-lib-injection-ssi.md | Generated PR body for historical stack layer 13 (SSI). |
| scripts/py315-stack/pr-bodies/13-compare.url | Generated GitHub compare URL for historical stack layer 13. |
| scripts/py315-stack/pr-bodies/12-vlad-315-profiling-dev-tooling.md | Generated PR body for historical stack layer 12 (dev tooling). |
| scripts/py315-stack/pr-bodies/12-vlad-315-lib-injection-ssi.md | Generated PR body for historical stack layer 12 (SSI). |
| scripts/py315-stack/pr-bodies/12-compare.url | Generated GitHub compare URL for historical stack layer 12. |
| scripts/py315-stack/pr-bodies/11-vlad-ddtracepy-315-profiling-asyncio-monitoring.md | Generated PR body for historical stack layer 11 (asyncio monitoring). |
| scripts/py315-stack/pr-bodies/11-vlad-315-profiling-dev-tooling.md | Generated PR body for historical stack layer 11 (dev tooling). |
| scripts/py315-stack/pr-bodies/11-compare.url | Generated GitHub compare URL for historical stack layer 11. |
| scripts/py315-stack/pr-bodies/10-vlad-ddtracepy-315-profiling-only.md | Generated PR body for historical stack layer 10 (profiling-only). |
| scripts/py315-stack/pr-bodies/10-vlad-ddtracepy-315-profiling-asyncio-monitoring.md | Generated PR body for historical stack layer 10 (asyncio monitoring). |
| scripts/py315-stack/pr-bodies/10-compare.url | Generated GitHub compare URL for historical stack layer 10. |
| scripts/py315-stack/pr-bodies/09-vlad-ddtracepy-315-profiling-only.md | Generated PR body for historical stack layer 9 (profiling-only). |
| scripts/py315-stack/pr-bodies/09-vlad-ddtracepy-315-profiling-collectors.md | Generated PR body for historical stack layer 9 (collectors). |
| scripts/py315-stack/pr-bodies/09-compare.url | Generated GitHub compare URL for historical stack layer 9. |
| scripts/py315-stack/pr-bodies/08-vlad-ddtracepy-315-profiling-native.md | Generated PR body for historical stack layer 8 (native ABI). |
| scripts/py315-stack/pr-bodies/08-vlad-ddtracepy-315-profiling-collectors.md | Generated PR body for historical stack layer 8 (collectors). |
| scripts/py315-stack/pr-bodies/08-compare.url | Generated GitHub compare URL for historical stack layer 8. |
| scripts/py315-stack/pr-bodies/07-vlad-profiling-native-test-install-subdir.md | Generated PR body for historical stack layer 7 (INSTALL_SUBDIR). |
| scripts/py315-stack/pr-bodies/07-vlad-ddtracepy-315-profiling-native.md | Generated PR body for historical stack layer 7 (native ABI). |
| scripts/py315-stack/pr-bodies/07-compare.url | Generated GitHub compare URL for historical stack layer 7. |
| scripts/py315-stack/pr-bodies/06-vlad-profiling-native-test-install-subdir.md | Generated PR body for historical stack layer 6 (INSTALL_SUBDIR). |
| scripts/py315-stack/pr-bodies/06-vlad-315-peripheral-compat.md | Generated PR body for historical stack layer 6 (peripheral compat). |
| scripts/py315-stack/pr-bodies/06-compare.url | Generated GitHub compare URL for historical stack layer 6. |
| scripts/py315-stack/pr-bodies/05-vlad-315-peripheral-compat.md | Generated PR body for historical stack layer 5 (peripheral compat). |
| scripts/py315-stack/pr-bodies/05-vlad-315-official-support.md | Generated PR body for historical stack layer 5 (official support). |
| scripts/py315-stack/pr-bodies/05-compare.url | Generated GitHub compare URL for historical stack layer 5. |
| scripts/py315-stack/pr-bodies/04-vlad-315-ci-autoregen-lockfiles.md | Generated PR body for historical stack layer 4 (lockfile regen). |
| scripts/py315-stack/pr-bodies/04-compare.url | Generated GitHub compare URL for historical stack layer 4. |
| scripts/py315-stack/pr-bodies/03-vlad-315-ci-matrix.md | Generated PR body for historical stack layer 3 (CI matrix). |
| scripts/py315-stack/pr-bodies/03-compare.url | Generated GitHub compare URL for historical stack layer 3. |
| scripts/py315-stack/pr-bodies/02-compare.url | Generated GitHub compare URL for historical stack layer 2. |
| scripts/py315-stack/pr-bodies/02-chore-315-wrapping-context.md | Generated PR body for historical stack layer 2 (wrapping context). |
| scripts/py315-stack/pr-bodies/01-gab-315-monitoring-multiplexer.md | Generated PR body for historical stack layer 1 (monitoring multiplexer). |
| scripts/py315-stack/pr-bodies/01-compare.url | Generated GitHub compare URL for historical stack layer 1. |
| scripts/py315-stack/open-all-draft-prs.sh | Helper to open compare URLs for drafting PRs in historical stack order. |
| scripts/py315-stack/MANUAL_EXISTING_PRS.md | Manual navigation notes for the live 5-PR stack and related PRs. |
| scripts/py315-stack/generate-pr-urls.sh | Generator for compare URLs and PR bodies (historical 14-PR chain). |
| scripts/py315-stack/DRAFT_PRS.md | Generated index of historical 14-PR compare URLs and bodies (archival). |
| scripts/profiles/compatibility_baselines.json | Adds saved compatibility baselines for 3.9–3.15 for the verifier script. |
| docs/cpython-diffs/analysis_314_to_315.md | New CPython 3.14→3.15 header/change analysis notes for Echion/profiling. |
| docs/contributing.rst | Adds link to the new profiling-on-new-CPython guide and updates toctree. |
| docs/contributing-testing.rst | Documents using scripts/run-profiling-tests for profiling validation on new Python versions. |
| docs/contributing-profiling-new-cpython.rst | New maintainer runbook for profiling bring-up on new CPython minors (stack/Echion, gating, CI, validation). |
| AGENTS.md | Documents the type-annotate skill in the project’s AI assistant guidance. |
| .claude/skills/type-annotate/SKILL.md | Adds the new type-annotate skill definition and workflow guidance. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| # Import _asyncio BEFORE asyncio to ensure the ModuleWatchdog callback is | ||
| # registered first. The callback fires when asyncio is subsequently imported. | ||
| # Importing asyncio triggers the ModuleWatchdog callback, which runs | ||
| # _call_init_asyncio() — exercising all the hasattr guards. | ||
| import asyncio | ||
|
|
||
| import ddtrace.profiling._asyncio as _asyncio_mod |
| failures.append(f"{suite}: was PASS in baseline, now FAIL — {cur.get('error', '?')}") | ||
|
|
||
| # Check sample count regression | ||
| if "wall_time_samples" in ref and "wall_time_samples" in cur: |
| - Tagged int shift changed: `(i << 2)` instead of `(i << 2)` — same for non-debug, | ||
| but `Py_TAGGED_SHIFT = 2` is now the canonical name. |
| ``validate_supported_configurations_v2_local_file`` GitLab CI job to fail, displaying the missing keys | ||
| in its output. A Datadog maintainer must add the key to the registry before the PR can merge. | ||
|
|
||
| .. toctree:: |
Profiling bring-up scripts, compatibility baselines, Echion migration runbook, and py315-stack PR navigation helpers (PR 12/14).
Point the 3.15 runbook row at this stack instead of closed #17294/hasattr guards, and draft paste-ready PR bodies that do not treat sys.monitoring as a 3.15-only API.
5059048 to
20c0559
Compare
8b78ec5 to
1c11f4f
Compare
prev: #19272
Description
Delta vs #19272.
Adds
docs/contributing-profiling-new-cpython.rst,docs/cpython-diffs/analysis_314_to_315.md,scripts/verify_profiler_compatibility.py,scripts/run-profiling-tests, compatibility baselines, AGENTS.md / type-annotate notes, andscripts/py315-stack/bring-up files (including stale draft PR bodies).No runtime profiler change.
Testing
Risks
Additional Notes
Docs and scripts only.
Contributes to #17817