perf(profiling): bound task stack collection

[taegyunkim]

Description

Bounds asyncio stack collection and applies an explicit task-priority frame budget after logical stack stitching.

• materializes at most DD_PROFILING_MAX_FRAMES physical thread frames
• materializes at most DD_PROFILING_MAX_FRAMES coroutine frames per task and stops assembling a logical task chain once its frame budget is full
• gives logical task frames first claim on the final reporting budget
• fills remaining capacity with synchronous leaf frames, followed by lower-priority event-loop roots
• emits an inline synchronous-frame omission marker when physical frames are removed between retained logical segments
• counts injected native and garbage-collection locations while selecting frames, preventing lower-priority physical context from displacing task context in the exporter
• conservatively reports task context alone when an on-CPU asyncio boundary lies beyond the bounded physical stack
• scales the Echion frame cache to 4 * max_frames, bounded between 256 and 1,024 entries

The branch now includes origin/main at eccb6f1d4a, including #19073. The merge preserves the upstream UnwindResult, truncation-status, native-frame-limit, and post-fork restart behavior while applying the effective frame limit to asyncio collection. It also preserves the 599-frame configuration clamp from #19076, which reserves one of the backend's 600 locations for the omitted-frame indicator.

JIRA: PROF-14213

Prerequisites

These independent changes should merge into main before this PR:

• refactor(profiling): clarify stack discovery limits #20352 clarifies the stack-discovery safety limit and extracts asyncio boundary detection without changing behavior.
• perf(profiling): scale Echion frame cache with frame limit #20351 scales the Echion frame cache with DD_PROFILING_MAX_FRAMES.

Testing

• Passed all 20 profiling_native CI matrix jobs. The exact local Python 3.12 ThreadSanitizer CI build command also passed against the merged tree, including all 23 native stack tests.
• Passed the complete Python 3.13 profiling suite after rebuilding the native extensions: 410 passed, 35 skipped, and 2 expected failures.
• Passed the targeted Python 3.13 gevent stack test for bounded greenlet discovery and the scaled frame-cache assertion.
• The profiling runs covered task-priority frame budgeting, stack truncation, cache scaling, post-fork frame-limit updates, garbage-collection frames, native frames, and task reservoir sampling.
• Passed scripts/lint checks, Python and C/C++ formatting, and git diff --check. Broad static analysis reported only existing repository warnings.
• scripts/run-benchmarks --list found no benchmark suite matching the changed Echion files.

Risks

Low DD_PROFILING_MAX_FRAMES values now intentionally prefer logical task ancestry over physical synchronous frames. This changes which portion of a mixed stack is reported, but preserves a bounded and logically meaningful task trace instead of allowing a deep physical stack to hide task context.

If the asyncio boundary is outside the bounded physical candidates, the sampler does not guess at overlap or concatenate potentially duplicated segments. It reports the bounded logical task stack alone.

The smaller frame cache can increase cache churn in workloads with many distinct code locations. It retains a 256-entry floor and scales with configured stack depth to balance reuse and memory.

Additional Notes

Task selection and render ordering are intentionally separate. Task frames receive budgeting priority, while retained segments are still rendered in logical leaf-to-root order.

The uppercase MAX_STACK_DISCOVERY_DEPTH constant remains a hard internal safety bound. The configured reporting and materialization budget is stored separately in stack_max_frames.

[cit-pr-commenter-54b7da]

Codeowners resolved as

Resolved from the full PR diff against main using the target branch CODEOWNERS file.
CODEOWNERS team requests not listed below are not required by the current file set.

ddtrace/internal/datadog/profiling/stack/echion/echion/cache.h          @DataDog/profiling-python
ddtrace/internal/datadog/profiling/stack/echion/echion/config.h         @DataDog/profiling-python
ddtrace/internal/datadog/profiling/stack/echion/echion/echion_sampler.h  @DataDog/profiling-python
ddtrace/internal/datadog/profiling/stack/echion/echion/stacks.h         @DataDog/profiling-python
ddtrace/internal/datadog/profiling/stack/echion/echion/tasks.h          @DataDog/profiling-python
ddtrace/internal/datadog/profiling/stack/echion/echion/threads.h        @DataDog/profiling-python
ddtrace/internal/datadog/profiling/stack/fuzz/fuzz_echion_stacks.cpp    @DataDog/profiling-python
ddtrace/internal/datadog/profiling/stack/fuzz/fuzz_echion_task_unwind.cpp  @DataDog/profiling-python
ddtrace/internal/datadog/profiling/stack/include/constants.hpp          @DataDog/profiling-python
ddtrace/internal/datadog/profiling/stack/include/stack_renderer.hpp     @DataDog/profiling-python
ddtrace/internal/datadog/profiling/stack/src/echion/greenlets.cc        @DataDog/profiling-python
ddtrace/internal/datadog/profiling/stack/src/echion/stacks.cc           @DataDog/profiling-python
ddtrace/internal/datadog/profiling/stack/src/echion/tasks.cc            @DataDog/profiling-python
ddtrace/internal/datadog/profiling/stack/src/echion/threads.cc          @DataDog/profiling-python
ddtrace/internal/datadog/profiling/stack/src/sampler.cpp                @DataDog/profiling-python
ddtrace/internal/datadog/profiling/stack/src/stack_renderer.cpp         @DataDog/profiling-python
ddtrace/internal/datadog/profiling/stack/test/test_sampling_cycle_state.cpp  @DataDog/profiling-python
releasenotes/notes/profiling-bound-task-stack-frames-5c8460b0d7e2118f.yaml  @DataDog/apm-python
tests/profiling/collector/test_asyncio_task_frame_budget.py             @DataDog/profiling-python
tests/profiling/collector/test_stack.py                                 @DataDog/profiling-python

[cit-pr-commenter-54b7da]

Circular import analysis

⚠️ Existing circular imports

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

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

[datadog-datadog-us1-prod]

✅ All CI checks and tests passed.

🎉 All green!

🧪 All tests passed
❄️ No new flaky tests detected

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

[cit-pr-commenter-54b7da]

Dependency direction analysis

⚠️ Existing dependency direction violations

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

Show existing violations (showing 5 of 218 highest severity)

ddtrace.internal.tracemethods -×-> ddtrace.trace  (internal-core -> product:tracing, score=133)
ddtrace.llmobs._evaluators.runner -×-> ddtrace.trace  (product:llmobs -> product:tracing, score=131)
ddtrace.internal.test_visibility.api -×-> ddtrace.trace  (product:ci_visibility -> product:tracing, score=131)
ddtrace.debugging._exception.replay -×-> ddtrace.trace  (product:debugging -> product:tracing, score=131)
ddtrace.appsec._listeners -×-> ddtrace.trace  (product:appsec -> product:tracing, score=131)

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