feat(python): add mem_domain 3.14/3.15 gate scenarios

MEM-domain heap-space feature coverage (off by default). Stacks on
gate-infra (PR-0), parallel to core gate scenarios (PR-0a).

Author: vlad-scherbich

scenarios/python_downstream_gate/README.md

@@ -1,53 +1,29 @@
 # Python downstream gate (dd-trace-py)
 
-Paired **3.14 (baseline)** and **3.15 (candidate)** prof-correctness scenarios
-exercise the Python profiling stack for the 3.14 → 3.15 migration. They are the
-intended default set when dd-trace-py triggers downstream CI on profiling changes.
-
-**Scenarios land in follow-up PRs** (core families first, then feature-specific
-pairs). This directory is an index only — not a runnable scenario.
+Two prof-correctness scenarios exercise **MEM domain** heap profiling on **3.14
+(baseline)** and **3.15 (candidate)**. This is **feature coverage** (off by
+default: `DD_PROFILING_MEMORY_MEM_DOMAIN_ENABLED`), not default-profiler gate.
 
 ## Scenarios
 
-| Family | 3.14 (baseline) | 3.15 (candidate) | PR |
-|--------|-----------------|---------------------|-----|
-| _(pending)_ | — | — | Core scenarios in follow-up PRs |
+| Family | 3.14 (baseline) | 3.15 (candidate) |
+|--------|-------------------|------------------|
+| mem-domain | `python_mem_domain_3.14` | `python_mem_domain_3.15` |
 
 ## Default downstream regexp
 
-Once scenarios are added, dd-trace-py should pass an explicit regexp (not the
-downstream workflow default of `python.*`). The regexp grows as families merge;
-see each PR for the current value.
-
-Override via `workflow_dispatch` → `test_scenarios`, or when triggering
-[`downstream-python.yml`](../../.github/workflows/downstream-python.yml) manually.
+```
+python_mem_domain_3\.(14|15)
+```
 
 ## Wheel install
 
-Every scenario builds against a **dd-trace-py wheel** via `DDTRACE_INSTALL_URL`
-(as `downstream-python.yml` does:
-`https://dd-trace-py-builds.s3.amazonaws.com/<sha>/install.sh`), pre-installed in
-the base image.
-
-- **All `*_3.15` folders** — PyPI wheels may not be published for 3.15 yet;
-  excluded from prof-correctness `main` CI (see `test_scenarios_exclude` in
-  [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml)).
-- **Wheel-only 3.14 folders** — scenarios that depend on unreleased ddtrace
-  features are also excluded from `main` CI until the feature ships.
+- **3.15** — wheel-only (`DDTRACE_INSTALL_URL`); excluded from `main` CI.
+- **3.14** — runs on `main` CI against PyPI ddtrace.
 
 ## Local run
 
 ```sh
 export DDTRACE_INSTALL_URL="https://dd-trace-py-builds.s3.amazonaws.com/<commit-sha>/install.sh"
-TEST_SCENARIOS='<gate-regexp>' go test -v -run TestScenarios
+TEST_SCENARIOS='python_mem_domain_3\.(14|15)' go test -v -run TestScenarios
 ```
-
-## Gate lifecycle
-
-This gate tests the **migration delta** (3.14 → 3.15). It is time-boxed: retire
-the paired 14v15 framing at 3.15 GA and fold workloads into steady-state
-prof-correctness on {oldest, newest} supported Python versions.
-
-## Further reading
-
-- prof-correctness downstream wiring: [README](../../README.md#downstream-from-dd-trace-py)

scenarios/python_mem_domain_3.14/Dockerfile

@@ -0,0 +1,18 @@
+ARG BASE_IMAGE="prof-python-3.14"
+FROM $BASE_IMAGE
+
+COPY ./scenarios/python_mem_domain_3.14/requirements.txt /app/requirements.txt
+RUN pip install -r /app/requirements.txt
+
+COPY ./scenarios/python_mem_domain_3.14/main.py /app/main.py
+WORKDIR /app
+
+ENV EXECUTION_TIME_SEC=15
+ENV DD_PROFILING_HEAP_ENABLED=true
+ENV DD_PROFILING_MEMORY_MEM_DOMAIN_ENABLED=true
+ENV DD_PROFILING_HEAP_SAMPLE_SIZE=524288
+ENV DD_PROFILING_UPLOAD_INTERVAL=5
+ENV DD_PROFILING_STACK_ENABLED=false
+ENV DD_PROFILING_LOCK_ENABLED=false
+
+CMD python main.py

scenarios/python_mem_domain_3.14/expected_profile.json

@@ -0,0 +1,18 @@
+{
+  "test_name": "python_mem_domain_3.14",
+  "pprof-regex": "profiles\\.([2-9]|[1-9][0-9]+)\\..*\\.pprof$",
+  "allow_first_profile_failure": true,
+  "stacks": [
+    {
+      "profile-type": "heap-space",
+      "stack-content": [
+        {
+          "regular_expression": ".*allocate_mem_domain_buffer.*",
+          "percent": 50,
+          "error_margin": 50
+        }
+      ]
+    }
+  ],
+  "scale_by_duration": false
+}

scenarios/python_mem_domain_3.14/main.py

@@ -0,0 +1,23 @@
+import os
+import time
+
+from ddtrace.profiling import Profiler
+
+# Keep MEM-domain allocations live across heap snapshot uploads.
+LIVE: list[bytearray] = []
+
+BUF_BYTES = 16 * 1024 * 1024
+
+
+def allocate_mem_domain_buffer() -> None:
+    LIVE.append(bytearray(BUF_BYTES))
+
+
+if __name__ == "__main__":
+    prof = Profiler()
+    prof.start()
+
+    allocate_mem_domain_buffer()
+    time.sleep(int(os.environ.get("EXECUTION_TIME_SEC", "15")))
+
+    prof.stop()

scenarios/python_mem_domain_3.14/requirements.txt

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

scenarios/python_mem_domain_3.15/Dockerfile

@@ -0,0 +1,19 @@
+ARG BASE_IMAGE="prof-python-3.15"
+FROM $BASE_IMAGE
+
+# ddtrace is pre-installed in the base image when DDTRACE_INSTALL_URL is set
+# (dd-trace-py downstream CI). Do not pip-install here — PyPI wheels may not
+# exist for 3.15 yet.
+
+COPY ./scenarios/python_mem_domain_3.15/main.py /app/main.py
+WORKDIR /app
+
+ENV EXECUTION_TIME_SEC=15
+ENV DD_PROFILING_HEAP_ENABLED=true
+ENV DD_PROFILING_MEMORY_MEM_DOMAIN_ENABLED=true
+ENV DD_PROFILING_HEAP_SAMPLE_SIZE=524288
+ENV DD_PROFILING_UPLOAD_INTERVAL=5
+ENV DD_PROFILING_STACK_ENABLED=false
+ENV DD_PROFILING_LOCK_ENABLED=false
+
+CMD python main.py

scenarios/python_mem_domain_3.15/expected_profile.json

@@ -0,0 +1,18 @@
+{
+  "test_name": "python_mem_domain_3.15",
+  "pprof-regex": "profiles\\.([2-9]|[1-9][0-9]+)\\..*\\.pprof$",
+  "allow_first_profile_failure": true,
+  "stacks": [
+    {
+      "profile-type": "heap-space",
+      "stack-content": [
+        {
+          "regular_expression": ".*allocate_mem_domain_buffer.*",
+          "percent": 50,
+          "error_margin": 50
+        }
+      ]
+    }
+  ],
+  "scale_by_duration": false
+}

scenarios/python_mem_domain_3.15/main.py

@@ -0,0 +1,23 @@
+import os
+import time
+
+from ddtrace.profiling import Profiler
+
+# Keep MEM-domain allocations live across heap snapshot uploads.
+LIVE: list[bytearray] = []
+
+BUF_BYTES = 16 * 1024 * 1024
+
+
+def allocate_mem_domain_buffer() -> None:
+    LIVE.append(bytearray(BUF_BYTES))
+
+
+if __name__ == "__main__":
+    prof = Profiler()
+    prof.start()
+
+    allocate_mem_domain_buffer()
+    time.sleep(int(os.environ.get("EXECUTION_TIME_SEC", "15")))
+
+    prof.stop()

scenarios/python_mem_domain_3.15/requirements.txt

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