feat(python): add core 3.14/3.15 gate scenarios (lock, exceptions, async_gen)

Add six paired scenarios for the migration gate with lock-release and lock
name labels plus exception type labels. Stacks on gate-infra (PR-0).

Author: vlad-scherbich

README.md

@@ -55,7 +55,7 @@ Both use [dd-octo-sts](https://github.com/DataDog/dd-octo-sts-action) (`dd-trace
 **Inputs:**
 
 - `dd_trace_py_commit_sha` — commit to test (required)
-- `test_scenarios` — regexp passed to `TEST_SCENARIOS` (see the [3.14/3.15 migration gate index](scenarios/python_downstream_gate/README.md); the downstream workflow default alone is `python.*`)
+- `test_scenarios` — regexp passed to `TEST_SCENARIOS` (dd-trace-py passes the [6-scenario 3.14/3.15 migration gate](scenarios/python_downstream_gate/README.md); the downstream workflow default alone is `python.*`)
 
 ## Creating new tests 
 

scenarios/python_async_gen_3.14/Dockerfile

@@ -0,0 +1,13 @@
+ARG BASE_IMAGE="prof-python-3.14"
+FROM $BASE_IMAGE
+
+RUN pip install ddtrace
+
+COPY ./scenarios/python_async_gen_3.14/main.py /app/main.py
+WORKDIR /app
+
+ENV EXECUTION_TIME_SEC=8
+ENV _DD_PROFILING_STACK_ADAPTIVE_SAMPLING_ENABLED=0
+ENV DD_PROFILING_ENABLED=true
+
+CMD ddtrace-run python main.py

scenarios/python_async_gen_3.14/expected_profile.json

@@ -0,0 +1,16 @@
+{
+  "test_name": "python_async_gen_3.14",
+  "stacks": [
+    {
+      "profile-type": "wall-time",
+      "stack-content": [
+        {
+          "regular_expression": ".*async_gen_work.*",
+          "percent": 50,
+          "error_margin": 100
+        }
+      ]
+    }
+  ],
+  "scale_by_duration": false
+}

scenarios/python_async_gen_3.14/main.py

@@ -0,0 +1,23 @@
+import asyncio
+import os
+
+
+async def async_gen_work() -> None:
+    async def ticker() -> object:
+        for i in range(1_000_000):
+            yield i
+            if i % 10_000 == 0:
+                await asyncio.sleep(0)
+
+    async for _ in ticker():
+        pass
+
+
+async def main() -> None:
+    await asyncio.sleep(0.5)
+    execution_time_sec = float(os.environ.get("EXECUTION_TIME_SEC", "8"))
+    await asyncio.wait_for(async_gen_work(), timeout=execution_time_sec)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

scenarios/python_async_gen_3.14/requirements.txt

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

scenarios/python_async_gen_3.15/Dockerfile

@@ -0,0 +1,11 @@
+ARG BASE_IMAGE="prof-python-3.15"
+FROM $BASE_IMAGE
+
+COPY ./scenarios/python_async_gen_3.15/main.py /app/main.py
+WORKDIR /app
+
+ENV EXECUTION_TIME_SEC=8
+ENV _DD_PROFILING_STACK_ADAPTIVE_SAMPLING_ENABLED=0
+ENV DD_PROFILING_ENABLED=true
+
+CMD ddtrace-run python main.py

scenarios/python_async_gen_3.15/expected_profile.json

@@ -0,0 +1,16 @@
+{
+  "test_name": "python_async_gen_3.15",
+  "stacks": [
+    {
+      "profile-type": "wall-time",
+      "stack-content": [
+        {
+          "regular_expression": ".*async_gen_work.*",
+          "percent": 50,
+          "error_margin": 100
+        }
+      ]
+    }
+  ],
+  "scale_by_duration": false
+}

scenarios/python_async_gen_3.15/main.py

@@ -0,0 +1,23 @@
+import asyncio
+import os
+
+
+async def async_gen_work() -> None:
+    async def ticker() -> object:
+        for i in range(1_000_000):
+            yield i
+            if i % 10_000 == 0:
+                await asyncio.sleep(0)
+
+    async for _ in ticker():
+        pass
+
+
+async def main() -> None:
+    await asyncio.sleep(0.5)
+    execution_time_sec = float(os.environ.get("EXECUTION_TIME_SEC", "8"))
+    await asyncio.wait_for(async_gen_work(), timeout=execution_time_sec)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

scenarios/python_async_gen_3.15/requirements.txt

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

scenarios/python_downstream_gate/README.md

@@ -1,53 +1,50 @@
 # 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.
+Six prof-correctness scenarios exercise the profiling stack on **3.14
+(baseline)** and **3.15 (candidate)** for the same workloads. They are the
+default set when dd-trace-py triggers downstream CI on profiling changes.
 
 ## Scenarios
 
-| Family | 3.14 (baseline) | 3.15 (candidate) | PR |
-|--------|-----------------|---------------------|-----|
-| _(pending)_ | — | — | Core scenarios in follow-up PRs |
+| Family | 3.14 (baseline) | 3.15 (candidate) |
+|--------|-------------------|------------------|
+| exceptions | `python_exceptions_3.14` | `python_exceptions_3.15` |
+| async-gen | `python_async_gen_3.14` | `python_async_gen_3.15` |
+| lock | `python_lock_3.14` | `python_lock_3.15` |
+
+## Profiler coverage
+
+| Family | Profile type asserted | Collectors / setup |
+|--------|----------------------|--------------------|
+| exceptions | `exception-samples` + `exception type` | Exception profiler |
+| async-gen | `wall-time` | Full profiler via `ddtrace-run`; asyncio async-generator workload |
+| lock | `lock-acquire` + `lock-release` + `lock name` | Lock profiler; threaded lock churn |
+
+Feature-specific pairs (mem_domain, live_heap) and extended coverage (cpu, alloc,
+asyncio, …) land in follow-up PRs.
 
 ## 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.
+```
+python_(exceptions|async_gen|lock)_3\.(14|15)
+```
 
 Override via `workflow_dispatch` → `test_scenarios`, or when triggering
 [`downstream-python.yml`](../../.github/workflows/downstream-python.yml) manually.
 
 ## 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.
+- **All `*_3.15` folders** use `DDTRACE_INSTALL_URL` (excluded from `main` CI).
+- **3.14 folders** run on prof-correctness `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_(exceptions|async_gen|lock)_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
 
+- Gate infra: PR stacking from `vlad/gate-infra`
 - prof-correctness downstream wiring: [README](../../README.md#downstream-from-dd-trace-py)