[python_cpu_sleep_sync_3.12] add CPU/sleep attribution scenario (PROF-14213) (#128)

* [python_cpu_sleep_sync_3.12] add CPU/sleep attribution scenario (PROF-14213)

New scenario that alternates 10 ms CPU bursts with 50 ms sleeps in sync
mode, asserting on (a) total CPU consumed (167M ns/wall-sec, ±25%) and
(b) cpu_burst self-attribution as % of cpu-time profile (50% ±15%).

The 50% baseline codifies the architectural attribution ceiling
documented in the python-cpu-accuracy survey (Finding 2): with 10 ms
bursts sampled at ~10 ms cadence, ~50% of CPU lands on the next sample's
stack — typically the sleep frame.

Adaptive sampling is disabled (_DD_PROFILING_STACK_ADAPTIVE_SAMPLING_ENABLED=0).

Also adds base_images/Dockerfile.python-3.12.

* [python_cpu_sleep_sync_3.12] restore upstream-CI comments in Dockerfile.python-3.12

Code-review follow-up: keep the 3.12 base image as a one-line diff against
the 3.11 template so the comment explaining DDTRACE_INSTALL_URL (used by
dd-trace-py downstream CI) and the commented-out DD_TRACE_DEBUG line stay
in sync across versions.

Author: taegyunkim

base_images/Dockerfile.python-3.12

@@ -0,0 +1,13 @@
+FROM python:3.12 AS base
+
+# When set, download and run this install script to pre-install ddtrace.
+# Used by upstream dd-trace-py CI to test with just-built wheels from S3.
+ARG DDTRACE_INSTALL_URL=""
+RUN if [ -n "$DDTRACE_INSTALL_URL" ]; then \
+      curl -fsSL "$DDTRACE_INSTALL_URL" | bash; \
+    fi
+
+ENV DD_PROFILING_ENABLED=true
+ENV DD_TRACE_ENABLED=false
+# ENV DD_TRACE_DEBUG=true
+ENV DD_PROFILING_OUTPUT_PPROF="/app/data/profiles"

scenarios/python_cpu_sleep_sync_3.12/Dockerfile

@@ -0,0 +1,15 @@
+ARG BASE_IMAGE="prof-python-3.12"
+FROM $BASE_IMAGE
+
+WORKDIR /usr/src/app
+
+COPY ./scenarios/python_cpu_sleep_sync_3.12/ /usr/src/app
+
+RUN chmod 644 /usr/src/app/main.py
+RUN pip install --no-cache-dir -r requirements.txt
+
+ENV EXECUTION_TIME_SEC=30
+ENV DD_PROFILING_MEMORY_ENABLED=false
+ENV _DD_PROFILING_STACK_ADAPTIVE_SAMPLING_ENABLED=0
+
+CMD ddtrace-run python main.py

scenarios/python_cpu_sleep_sync_3.12/expected_profile.json

@@ -0,0 +1,21 @@
+{
+  "test_name": "python_cpu_sleep_sync_3.12",
+  "scale_by_duration": true,
+  "stacks": [
+    {
+      "profile-type": "cpu-time",
+      "stack-content": [
+        {
+          "regular_expression": ".*",
+          "value": 167000000,
+          "error_margin": 25
+        },
+        {
+          "regular_expression": ".*cpu_burst.*",
+          "percent": 50,
+          "error_margin": 15
+        }
+      ]
+    }
+  ]
+}

scenarios/python_cpu_sleep_sync_3.12/main.py

@@ -0,0 +1,24 @@
+import os
+import time
+
+
+def cpu_burst(target_seconds: float) -> int:
+    deadline = time.monotonic() + target_seconds
+    x = 0x1234
+    while time.monotonic() < deadline:
+        x = (x * 48271) % 2147483647
+    return x
+
+
+def main() -> None:
+    execution_time_sec = float(os.environ.get("EXECUTION_TIME_SEC", "30"))
+    cpu_seconds = 0.01
+    off_cpu = 0.05
+    deadline = time.monotonic() + execution_time_sec
+    while time.monotonic() < deadline:
+        time.sleep(off_cpu)
+        cpu_burst(cpu_seconds)
+
+
+if __name__ == "__main__":
+    main()

scenarios/python_cpu_sleep_sync_3.12/requirements.txt

@@ -0,0 +1 @@
+ddtrace