perf(profiling): scale Echion frame cache with frame limit

[taegyunkim]

Description

Scale Echion's retained frame cache to four times the configured maximum frame count, bounded between 256 and 1024 entries. Cache capacity can now be adjusted while the sampler is stopped, and shrinking immediately evicts least-recently-used entries.

JIRA: PROF-14213

Testing

• Added native LRU cache coverage for capacity clamping and least-recently-used eviction on shrink.
• scripts/run-tests --venv 13bd2ac -- tests/profiling/collector/test_stack.py -k 'test_collect_truncate or test_native_frame_limit_scales_cache or test_set_max_frames_after_fork_restart or test_asyncio_discovery_ignores_plain_stack_limit or test_collect_gevent_thread_task' (Python 3.10 with gevent): 5 passed, 440 deselected.
• scripts/lint checks: passed.
• scripts/check-releasenotes: passed.
• scripts/run-benchmarks --list ...: no benchmark suites match these files, so no benchmark was run.

Risks

The smaller cache can increase frame-cache churn for shallow frame limits. The 256-entry floor bounds that risk, while the existing 1024-entry capacity remains the ceiling for larger limits.

Additional Notes

This is an independent prerequisite for #19085 and intentionally excludes task stack budgeting, stack-discovery refactors, omission markers, and gevent budgeting.

[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/echion_sampler.h  @DataDog/profiling-python
ddtrace/internal/datadog/profiling/stack/include/constants.hpp          @DataDog/profiling-python
ddtrace/internal/datadog/profiling/stack/src/sampler.cpp                @DataDog/profiling-python
ddtrace/internal/datadog/profiling/stack/test/CMakeLists.txt            @DataDog/profiling-python
ddtrace/internal/datadog/profiling/stack/test/test_cache.cpp            @DataDog/profiling-python
releasenotes/notes/profiling-scale-frame-cache-9c206653796fb780.yaml    @DataDog/apm-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

[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._integrations.langgraph -×-> ddtrace.trace  (product:llmobs -> product:tracing, score=131)
ddtrace.internal.ci_visibility.filters -×-> ddtrace.trace  (product:ci_visibility -> product:tracing, score=131)
ddtrace.llmobs._integrations.google_adk -×-> ddtrace.trace  (product:llmobs -> product:tracing, score=131)
ddtrace.llmobs._integrations.mcp -×-> ddtrace.trace  (product:llmobs -> 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

[datadog-datadog-prod-us1]

✅ 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: 028a1e4 | Docs | View more details | Give us feedback!}