fix(profiling): align frame limit with backend location cap (#19076)

## Description

Aligns profiling frame-limit configuration with the backend's [600-location limit](https://datadoghq.atlassian.net/wiki/spaces/PROF/pages/5307007274/Profiling+Libraries+Frame+Truncation+Behaviors).

- raises the native exporter cap from 512 to 599 captured frames
- reserves the 600th backend location for the synthetic `<N frames omitted>` indicator on truncated stacks
- clamps `DD_PROFILING_MAX_FRAMES` to 599 in `ddtrace.internal.settings.profiling`
- preserves configured values from 513 through 599 instead of reducing them to 512 in the native exporter
- ensures collectors receive the same effective configured limit

JIRA: [PROF-14213](https://datadoghq.atlassian.net/browse/PROF-14213?atlOrigin=eyJpIjoiNWFmMTNkMDg2MmJjNDVlZTlkN2JlNGZkMjg3ZWZiYzEiLCJwIjoiaiJ9)

## Testing

- Added configuration tests covering the default, values below the maximum captured-frame limit, the exact 599-frame limit, and values at or above the 600-location backend limit.
- Ran `TestMaxFramesConfig` on Python 3.9, all 6 tests passed. The editable install also rebuilt the native extension successfully.
- Completed a clean Python 3.14 native build for the initial change.
- Ran `scripts/lint checks`, targeted formatting, spelling, and `git diff --check`. Broad lint checks reported only existing repository warnings.

## Risks

Configurations between 513 and 599 can now retain more frames than before. This matches the backend contract but can slightly increase per-sample work for users who explicitly configure values in that range.

Values of 600 and above are now clamped to 599 at configuration load instead of reaching individual collectors unchanged. This leaves one location for the omitted-frame indicator so truncated samples remain within the backend's 600-location cap.

## Additional Notes

This PR is the base of stacked #19073 and #19085, which propagate the limit into Echion and bound task-aware stack collection.

[PROF-14213]: https://datadoghq.atlassian.net/browse/PROF-14213?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiaiJ9


Co-authored-by: taegyun.kim <taegyun.kim@datadoghq.com>

Author: taegyunkim

ddtrace/internal/datadog/profiling/dd_wrapper/include/constants.hpp

@@ -7,9 +7,11 @@
 // is for ddtrace/settings/profiling.py:ProfilingConfig.max_frames, but should conform
 constexpr unsigned int g_default_max_nframes = 64;
 
-// Maximum number of frames admissible in the Profiling backend.  If a user exceeds this number, then
-// their stacks may be silently truncated, which is unfortunate.
-constexpr unsigned int g_backend_max_nframes = 512;
+// Maximum number of locations admissible in the Profiling backend. Reserve one location for the
+// synthetic "<N frames omitted>" frame emitted when a stack is truncated.
+// Keep in sync with BACKEND_MAX_LOCATIONS and MAX_FRAMES in ddtrace/internal/settings/profiling.py.
+constexpr unsigned int g_backend_max_nlocations = 600;
+constexpr unsigned int g_backend_max_nframes = g_backend_max_nlocations - 1;
 
 // Default value for the max number of samples to keep in the StaticSamplePool
 constexpr size_t g_default_sample_pool_capacity = 4;

ddtrace/internal/settings/profiling.py

@@ -118,6 +118,18 @@ def _enrich_tags(tags: dict[str, str]) -> dict[str, str]:
     return tags
 
 
+# The profiling backend accepts at most this many locations per sample.
+BACKEND_MAX_LOCATIONS = 600
+# Reserve one location for the synthetic "<N frames omitted>" frame emitted when
+# a stack is truncated. Keep these constants in sync with g_backend_max_nlocations
+# and g_backend_max_nframes in constants.hpp.
+MAX_FRAMES = BACKEND_MAX_LOCATIONS - 1
+
+
+def _clamp_max_frames(value: str) -> int:
+    return min(int(value), MAX_FRAMES)
+
+
 class ProfilingConfig(DDConfig):
     __prefix__ = "dd.profiling"
 
@@ -198,9 +210,12 @@ def __init__(self, *args: t.Any, **kwargs: t.Any) -> None:
         int,
         "max_frames",
         default=64,
-        validator=validators.range(0, t.cast(int, float("inf"))),
+        parser=_clamp_max_frames,
+        validator=validators.range(0, MAX_FRAMES),
         help_type="Integer",
-        help="The maximum number of frames to capture in stack execution tracing",
+        help="The maximum number of frames to capture in stack execution tracing. Values above "
+        f"{MAX_FRAMES} are clamped so that truncated stacks, including the omitted-frame indicator, stay within "
+        f"the profiling backend's {BACKEND_MAX_LOCATIONS}-location limit.",
     )
 
     ignore_profiler = DDConfig.v(

releasenotes/notes/profiling-backend-max-frames-347fd7903802fd4c.yaml

@@ -0,0 +1,4 @@
+---
+fixes:
+  - |
+    profiling: Fixes inconsistent handling of ``DD_PROFILING_MAX_FRAMES`` by clamping it before stack collection so samples stay within the backend's 600-location limit.

tests/profiling/test_profiling_config.py

@@ -7,6 +7,24 @@
 from ddtrace.internal.settings.profiling import ProfilingConfig
 
 
+class TestMaxFramesConfig:
+    def test_default(self) -> None:
+        assert ProfilingConfig().max_frames == 64
+
+    @pytest.mark.parametrize("value", (600, 601, 10_000))
+    def test_clamps_to_backend_limit(self, monkeypatch: pytest.MonkeyPatch, value: int) -> None:
+        monkeypatch.setenv("DD_PROFILING_MAX_FRAMES", str(value))
+
+        # One of the backend's 600 locations is reserved for the omitted-frame indicator.
+        assert ProfilingConfig().max_frames == 599
+
+    @pytest.mark.parametrize("value", (512, 599))
+    def test_preserves_value_within_backend_limit(self, monkeypatch: pytest.MonkeyPatch, value: int) -> None:
+        monkeypatch.setenv("DD_PROFILING_MAX_FRAMES", str(value))
+
+        assert ProfilingConfig().max_frames == value
+
+
 class TestAdaptiveSamplingConfig:
     def test_defaults(self) -> None:
         config = ProfilingConfig()