chore(profiling): gate unsupported platforms

[KowalskiThomas]

Description

Instrumentation telemetry was reporting error-level logs on Windows such as:

Failed to load stack module (cannot import name '_stack' from partially initialized module 'ddtrace.internal.datadog.profiling.stack' ...), disabling stack profiling

Root cause: ddtrace/bootstrap/preload.py imports ddtrace.internal.settings.profiling unconditionally (before the DD_PROFILING_ENABLED gate). At import time that module ran _check_for_ddup_available() / _check_for_stack_available(), which try to import the native _ddup / _stack extensions. Those extensions are only built for 64-bit CPython < 3.15 on Linux/macOS (see the gate in setup.py), so on Windows the import always fails — surfacing as a confusing "partially initialized module ... circular import" ImportError — and the module emitted ERROR-level telemetry. Profiling was only ever disabled as a side effect of that failed import; there was no positive platform check.

Changes:

• Add _is_platform_supported() in ddtrace/internal/settings/profiling.py, mirroring the build-time gate in setup.py (64-bit Linux/macOS, CPython < 3.15).
• Short-circuit the native availability probes on unsupported platforms: disable config.enabled / config.stack.enabled (and exception / native_heap) quietly via a debug log, instead of attempting the native imports and emitting ERROR-level "Failed to load ... module" telemetry for an expected, advertised-as-unsupported condition. Behavior on supported platforms is unchanged.
• Make the ddtrace/profiling/bootstrap/sitecustomize.py gate reuse the same helper so exotic unsupported cases (e.g. 32-bit macOS, Python 3.15+) are also caught, in addition to the existing Windows / 32-bit Linux messages.
• Add a release note.

Testing

Added a regression test test_unsupported_platform_disables_profiling_quietly in tests/profiling/test_profiler.py that mocks platform.system() to "Windows", imports the profiling settings, and asserts profiling is disabled and no "Failed to load" telemetry is emitted. Existing test_stack_failure_telemetry_logging / test_libdd_failure_telemetry_logging continue to assert the ERROR telemetry still fires on supported platforms.

Automated validation performed in this environment: ruff format --check and ruff check pass on all changed files; files byte-compile; the _is_platform_supported() decision table was verified against the setup.py gate. The native extensions are not built in this sandbox, so the profiling test suite could not be executed here.

TODO (human): validate in real services in staging and confirm no new crashes.

Risks

Low. On supported platforms (64-bit Linux/macOS, CPython < 3.15) the code path is unchanged — the native probes and their ERROR telemetry still run exactly as before. On unsupported platforms the profiler was already non-functional; this change only suppresses misleading ERROR telemetry and disables the config explicitly rather than implicitly.

Additional Notes

The helper intentionally duplicates the setup.py gate logic; a comment in both places notes they must be kept in sync.

Pre-review checklist

• The changes have been tested in real services in staging
• The PR does not result in new crashes

---

PR by Bits - View session in Datadog

Comment @DataDog to request changes

[datadog-datadog-prod-us1]

View session in Datadog

Bits Code status: ✅ Done

CI Auto-fix: Disabled | Enable

Comment @DataDog to request changes

[datadog-datadog-prod-us1]

I can only run on private repositories.

[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/settings/profiling.py                                  @DataDog/profiling-python
ddtrace/profiling/bootstrap/sitecustomize.py                            @DataDog/profiling-python
releasenotes/notes/fix-profiling-unsupported-platform-telemetry-dca6469c9e276b1a.yaml  @DataDog/apm-python
tests/profiling/test_profiler.py                                        @DataDog/profiling-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.appsec._listeners -×-> ddtrace.trace  (product:appsec -> product:tracing, score=132)
ddtrace.llmobs._integrations.vertexai -×-> ddtrace.trace  (product:llmobs -> product:tracing, score=132)
ddtrace.llmobs._integrations.base -×-> ddtrace.trace  (product:llmobs -> product:tracing, score=132)
ddtrace.internal.ci_visibility.filters -×-> ddtrace.trace  (product:ci_visibility -> 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

[datadog-datadog-prod-us1]

 

✨ Unblock PR with BitsAI

⚠️ Warnings

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

🚦 3 Pipeline jobs failed

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

View more details · View in GitLab

Pytorch Unit Tests (with GPU) | unit-tests — 🔧 Needs a code fix, caused by this PR

View more details · View in GitHub Actions

ImportError: No module named 'tests._ddtest_env_helpers' in tests/profiling/test_pytorch.py while importing test module.

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

View more details · View in GitLab

📋 Copy fix prompt

CI on my pull request is failing. Help me find and fix the root cause of each failing job below — they were flagged as caused by changes in this PR, so focus on the diff. For each job, explain the failure and propose a fix.

Before you start, set up the Datadog software-delivery tooling so you can
query the CI data yourself:

1. Check whether you already have the Datadog software-delivery MCP tools
   (e.g. a `search_datadog_ci_pipeline_events` tool) and the `unblock-pr` skill.
2. If either is missing, STOP and ask me for permission before installing
   anything. Do not install or run anything until I have said yes.
3. Only with my explicit approval, set up the Datadog software-delivery MCP
   server and skills by following:
     https://docs.datadoghq.com/getting_started/software_delivery_mcp_tools/
   then restart so the skill is picked up.
4. If I decline, skip all of the above and work from the context below alone.

Then run /unblock-pr — it will pull the CI data itself. The job context below is what we already know.

If /unblock-pr is not available — because I declined the setup above, or it did not install — work from the context below instead.

Datadog has already classified this failure as caused by changes in this PR.
Take that as given and work the fix:

1. Locate the change. Diff this branch against its base and find the change
   that produces this error. Explain the mechanism, don't just name a file:
     git fetch origin && git diff $(git merge-base origin/main HEAD)...HEAD
2. Reproduce it locally. Run the failing job's command or test before
   proposing anything.
3. Propose the smallest fix that addresses the root cause — not a workaround,
   not a broadened assertion, not a disabled or skipped test.
4. Re-run the same command to confirm, and say exactly what you ran.
5. If the failure turns out to be intermittent rather than deterministic, say
   so plainly instead of "fixing" it — that is a flaky test, and patching it
   hides the problem.

If the right move is to re-run the job rather than change code, use the job
link in the context below. For GitHub Actions: `gh run rerun <run-id> --failed`,
where the run ID is the number after `/runs/` in that URL (not the trailing
number, which is the job ID).

Branch: dd/kowalski/fix-profiling-unsupported-platform-gate

Pytorch Unit Tests (with GPU) | unit-tests
Commit: 97972566f5219b5e78067acd4230de486bcdd273
Error (code / test):
ImportError: No module named 'tests._ddtest_env_helpers' in tests/profiling/test_pytorch.py while importing test module.
CI job: https://github.com/DataDog/dd-trace-py/actions/runs/34136826853/job/101789654752

ℹ️ 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: 1544cc5 | Docs | View more details | Give us feedback!}