docs(profiling-315): py3.15 dev tooling and CPython upgrade runbook

[vlad-scherbich]

Description

Delta vs #19272: adds Python 3.15 profiling developer tooling and documentation, including the CPython upgrade runbook, 3.14→3.15 analysis, compatibility baselines, the profiling stack map, and fail-closed compatibility/test scripts.

This PR changes no runtime profiler behavior.

Layer	Meaning	Which PR
Compiled	Native prerequisite	#19269
Armed	Runtime prerequisite	#19272
Observable	Developer docs, scripts, and baselines	this PR

Testing

Risks

Additional Notes

Parent: #19272. changelog/no-changelog.

[datadog-prod-us1-3]

 

✨ Unblock PR with BitsAI

⚠️ Warnings

❌ Your PR has failed checks. Please review the issues below and take necessary action before merging.

🚦 6 Pipeline jobs failed

DataDog/apm-reliability/dd-trace-py | build_docs — 🔧 Needs a code fix, caused by this PR

View more details · View in GitLab

DataDog/apm-reliability/dd-trace-py | profiling_native_py315: [3.15, valgrind] — 🔧 Needs a code fix, caused by this PR

View more details · View in GitLab

DataDog/apm-reliability/dd-trace-py | download_dependency_wheels: [3.15.0rc1, 3.15]

View more details · View in GitLab

View all 6 failed jobs.

ℹ️ Info

No other issues found (see more)

🧪 All tests passed
❄️ No new flaky tests detected

Useful? React with 👍 / 👎

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: b9b9775 | Docs | View more details | Give us feedback!}

[cit-pr-commenter-54b7da]

Codeowners resolved as

Resolved from the full PR diff against vlad/ddtracepy-315-profiling-asyncio-monitoring using the target branch CODEOWNERS file.
CODEOWNERS team requests not listed below are not required by the current file set.

docs/contributing-profiling-new-cpython.rst                             @DataDog/python-guild
docs/contributing-testing.rst                                           @DataDog/python-guild
docs/contributing.rst                                                   @DataDog/python-guild
docs/cpython-diffs/analysis_314_to_315.md                               @DataDog/python-guild
scripts/profiles/compatibility_baselines.json                           @DataDog/profiling-python
scripts/py315-stack/PROFILING_STACK.md                                  @DataDog/python-guild
scripts/run-profiling-tests                                             @DataDog/python-guild
scripts/verify_profiler_compatibility.py                                @DataDog/python-guild
tests/internal/test_profiler_compat_fail_closed.py                      @DataDog/apm-core-python

[cit-pr-commenter-54b7da]

Circular import analysis

⚠️ Existing circular imports

There are 3 circular imports that already exist on the base branch and have not been changed by this PR.

ddtrace.llmobs -> ddtrace.llmobs._evaluators -> ddtrace.llmobs._evaluators.format -> ddtrace.llmobs._experiment -> ddtrace.llmobs
ddtrace.errortracking._handled_exceptions.bytecode_injector -> ddtrace.errortracking._handled_exceptions.callbacks -> ddtrace.errortracking._handled_exceptions.collector -> ddtrace.errortracking._handled_exceptions.bytecode_reporting -> ddtrace.errortracking._handled_exceptions.bytecode_injector
ddtrace.appsec._asm_request_context -> ddtrace.appsec._iast._iast_request_context_base -> ddtrace.appsec._iast._iast_env -> ddtrace.appsec._iast.reporter -> ddtrace.appsec._exploit_prevention.stack_traces -> ddtrace.appsec._asm_request_context

[cit-pr-commenter-54b7da]

Dependency direction analysis

⚠️ Existing dependency direction violations

There are 230 dependency direction violations that already exist on the base branch and have not been changed by this PR.

Show existing violations (showing 5 of 230 highest severity)

ddtrace.internal.tracemethods -×-> ddtrace.trace  (internal-core -> product:tracing, score=134)
ddtrace.internal.opentelemetry.trace -×-> ddtrace.trace  (product:opentelemetry -> product:tracing, score=132)
ddtrace.internal.ci_visibility.recorder -×-> ddtrace.trace  (product:ci_visibility -> product:tracing, score=132)
ddtrace.llmobs._integrations.llama_index -×-> ddtrace.trace  (product:llmobs -> product:tracing, score=132)
ddtrace.llmobs._integrations.mcp -×-> ddtrace.trace  (product:llmobs -> product:tracing, score=132)

To see all violations, download the layers-base.json and layers-pr.json artifacts from this CI job and run:

uv run --script scripts/import-analysis/layers.py compare layers-base.json layers-pr.json

[Copilot]

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) and scripts/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.