chore(flask): emit pre-request web event

[litianningdatadog]

Description

The MicroVM /run request has to be observed before a web root span reads runtime identity. This PR keeps the request-starting event coverage scoped to Flask.

This adds a generic WEB_REQUEST_STARTING core event and emits it from Flask once method and path are known, before request context/root span creation. The event is intentionally not tied to MicroVMs or runtime-id refresh in this PR.

Testing

• scripts/lint fmt ddtrace/internal/core/__init__.py ddtrace/contrib/internal/flask/patch.py tests/contrib/flask/test_microvm_identity_refresh.py
• scripts/run-tests --venv e6872f6 tests/contrib/flask/test_microvm_identity_refresh.py -- -- -k microvm_identity_refresh

Risks

Low. The event is emitted on Flask request entry, but it has no listener in this PR. The no-listener path should be cheap.

Release note

None. This PR adds an internal event emitter with no customer-visible listener. Use changelog/no-changelog.

Additional Notes

Depends on #19778. Follow-up PR adds stdlib http.server support.

[cit-pr-commenter-54b7da]

Dependency direction analysis

⚠️ Existing dependency direction violations

There are 250 dependency direction violations that already exist on the base branch and have not been changed by this PR.

Show existing violations (showing 5 of 250 highest severity)

ddtrace.internal.tracemethods -×-> ddtrace.trace  (internal-core -> product:tracing, score=135)
ddtrace.llmobs._integrations.vertexai -×-> ddtrace.trace  (product:llmobs -> product:tracing, score=133)
ddtrace.aiguard._api_client -×-> ddtrace.trace  (product:aiguard -> product:tracing, score=133)
ddtrace.internal.test_visibility.api -×-> ddtrace.trace  (product:ci_visibility -> product:tracing, score=133)
ddtrace.llmobs._integrations.google_adk -×-> ddtrace.trace  (product:llmobs -> product:tracing, score=133)

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

[litianningdatadog]

We made this change to allow emit WEB_REQUEST_STARTING event regardless of enabled or not

[pr-commenter]

Benchmarks

Benchmark execution time: 2026-08-23 21:15:56

Comparing candidate commit 55acf22 in PR branch tianning.li/2-web-request-starting-event with baseline commit 1cbc151 in branch tianning.li/1-runtime-identity-refresh.

📊 Benchmarking dashboard

Found 0 performance improvements and 10 performance regressions! Performance is the same for 607 metrics, 10 unstable metrics.

Explanation

This is an A/B test comparing a candidate commit's performance against that of a baseline commit. Performance changes are noted in the tables below as:

• 🟩 = significantly better candidate vs. baseline
• 🟥 = significantly worse candidate vs. baseline

We compute a confidence interval (CI) over the relative difference of means between metrics from the candidate and baseline commits, considering the baseline as the reference.

If the CI is entirely outside the configured SIGNIFICANT_IMPACT_THRESHOLD (or the deprecated UNCONFIDENCE_THRESHOLD), the change is considered significant.

Feel free to reach out to #apm-benchmarking-platform on Slack if you have any questions.

More details about the CI and significant changes

You can imagine this CI as a range of values that is likely to contain the true difference of means between the candidate and baseline commits.

CIs of the difference of means are often centered around 0%, because often changes are not that big:

---------------------------------(------|---^--------)-------------------------------->
                              -0.6%    0%  0.3%     +1.2%
                                 |          |        |
         lower bound of the CI --'          |        |
sample mean (center of the CI) -------------'        |
         upper bound of the CI ----------------------'

As described above, a change is considered significant if the CI is entirely outside the configured SIGNIFICANT_IMPACT_THRESHOLD (or the deprecated UNCONFIDENCE_THRESHOLD).

For instance, for an execution time metric, this confidence interval indicates a significantly worse performance:

----------------------------------------|---------|---(---------^---------)---------->
                                       0%        1%  1.3%      2.2%      3.1%
                                                  |   |         |         |
       significant impact threshold --------------'   |         |         |
                      lower bound of CI --------------'         |         |
       sample mean (center of the CI) --------------------------'         |
                      upper bound of CI ----------------------------------'

scenario:httppropagationinject-ids_only

• 🟥 execution_time [+1.880µs; +2.065µs] or [+9.787%; +10.750%]

scenario:iastaspects-add_aspect

• 🟥 execution_time [+14.684µs; +18.496µs] or [+14.524%; +18.295%]

scenario:iastaspects-join_aspect

• 🟥 execution_time [+45.889µs; +49.632µs] or [+21.812%; +23.592%]

scenario:iastaspects-ljust_noaspect

• 🟥 execution_time [+53.383µs; +59.771µs] or [+18.394%; +20.596%]

scenario:iastaspects-title_aspect

• 🟥 execution_time [+64.481µs; +69.773µs] or [+24.044%; +26.017%]

scenario:iastaspectsospath-ospathbasename_aspect

• 🟥 execution_time [+140.240µs; +147.027µs] or [+34.434%; +36.101%]

scenario:iastaspectssplit-rsplit_aspect

• 🟥 execution_time [+15.690µs; +19.721µs] or [+11.026%; +13.859%]

scenario:span-start

• 🟥 execution_time [+1.501ms; +1.682ms] or [+9.937%; +11.133%]

scenario:telemetryaddmetric-1-count-metric-1-times

• 🟥 execution_time [+425.528ns; +474.391ns] or [+15.694%; +17.496%]

scenario:tracer-small

• 🟥 execution_time [+26.072µs; +28.365µs] or [+7.716%; +8.395%]

Unstable benchmarks

These benchmarks have a confidence interval too wide to call a change; treat them as noise rather than signal.

scenario:coreapiscenario-context_with_data_listeners

• unstable execution_time [-684.844ns; +799.866ns] or [-6.226%; +7.272%]

scenario:coreapiscenario-core_dispatch_1_listener

• unstable execution_time [-37.069ns; +29.281ns] or [-6.050%; +4.779%]

scenario:coreapiscenario-core_dispatch_50_listeners

• unstable execution_time [-1757.438ns; +1580.292ns] or [-10.219%; +9.189%]

scenario:coreapiscenario-core_dispatch_exception_listeners

• unstable execution_time [-1128.320ns; +1329.918ns] or [-8.762%; +10.327%]

scenario:coreapiscenario-core_dispatch_listeners

• unstable execution_time [-353.329ns; +302.453ns] or [-9.556%; +8.180%]

scenario:coreapiscenario-core_dispatch_no_args_listeners

• unstable execution_time [-276.751ns; +231.091ns] or [-9.449%; +7.890%]

scenario:coreapiscenario-core_dispatch_with_results_1_listener

• unstable execution_time [-87.561ns; +60.016ns] or [-7.594%; +5.205%]

scenario:coreapiscenario-core_dispatch_with_results_50_listeners

• unstable execution_time [-3404.779ns; +4559.248ns] or [-8.464%; +11.335%]

scenario:coreapiscenario-core_dispatch_with_results_listeners

• unstable execution_time [-732.690ns; +801.526ns] or [-9.190%; +10.053%]

scenario:packagesupdateimporteddependencies-import_many_stdlib_cached

• unstable execution_time [-53.470µs; +67.637µs] or [-8.383%; +10.604%]

[Copilot]

Pull request overview

This PR introduces a new core event (core.WEB_REQUEST_STARTING) intended to be emitted by web entry points as soon as HTTP method/path are known, but before request context/root span creation, enabling early observers (e.g., MicroVM lifecycle detection) across disparate server stacks.

Changes:

• Added WEB_REQUEST_STARTING to ddtrace.internal.core and emitted it from multiple supported web integrations (WSGI/ASGI/framework-specific) prior to request tracing.
• Added a new http_server contrib integration that patches http.server.BaseHTTPRequestHandler.parse_request() to emit the event for “raw stdlib server” use cases.
• Added per-integration tests asserting the event is emitted (including on unmatched routes where applicable), plus integration registry / suite wiring for http_server.

Reviewed changes

Copilot reviewed 39 out of 40 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/contrib/tornado/test_microvm_identity_refresh.py	New test coverage asserting Tornado emits the pre-request event with method/path.
tests/contrib/suitespec.yml	Adds http_server component + suite selection wiring for contrib test runs.
tests/contrib/sanic/test_sanic.py	Adds assertions that Sanic emits the pre-request event before tracing starts.
tests/contrib/pyramid/test_microvm_identity_refresh.py	New Pyramid tests covering event emission (including tracing-disabled behavior).
tests/contrib/molten/test_microvm_identity_refresh.py	New Molten tests asserting event emission from the WSGI entry point.
tests/contrib/http_server/test_microvm_identity_refresh.py	New tests validating http.server parse_request emits event only for well-formed requests.
tests/contrib/http_server/test_http_server_patch.py	Patch/unpatch/get_version coverage for the new http_server integration.
tests/contrib/http_server/init.py	Establishes the contrib test package for http_server.
tests/contrib/flask/test_microvm_identity_refresh.py	New Flask tests asserting event emission ordering (incl. before WSGI middleware).
tests/contrib/falcon/test_microvm_identity_refresh.py	New Falcon middleware tests asserting event emission on 404 and normal routes.
tests/contrib/django/test_microvm_identity_refresh.py	New Django tests asserting event emission before URL resolution.
tests/contrib/cherrypy/test_microvm_identity_refresh.py	New CherryPy tests asserting event emission at request start hook.
tests/contrib/bottle/test_microvm_identity_refresh.py	New Bottle tests asserting event emission at WSGI entry point.
tests/contrib/asgi/test_microvm_identity_refresh.py	New ASGI middleware tests asserting event emission and sub-app suppression behavior.
supported-configurations.json	Registers DD_TRACE_HTTP_SERVER_ENABLED and DD_HTTP_SERVER_SERVICE in the configuration registry.
scripts/integration_registry/registry.yaml	Registers http_server as a tested, internal integration.
riotfile.py	Adds a dedicated http_server riot venv target for contrib tests.
docs/integrations.rst	Adds http_server to the integrations documentation index.
ddtrace/internal/settings/_supported_configurations.py	Regenerated supported configuration list/aliases to include new keys.
ddtrace/internal/core/init.py	Defines the WEB_REQUEST_STARTING event constant.
ddtrace/contrib/internal/tornado/handlers.py	Emits WEB_REQUEST_STARTING at Tornado request execution start.
ddtrace/contrib/internal/sanic/patch.py	Emits WEB_REQUEST_STARTING at the shared Sanic request-span entry point.
ddtrace/contrib/internal/pyramid/trace.py	Refactors tween to always emit WEB_REQUEST_STARTING (even if tracing disabled) before tracing context.
ddtrace/contrib/internal/molten/patch.py	Emits WEB_REQUEST_STARTING at Molten’s WSGI entry wrapper.
ddtrace/contrib/internal/http_server/patch.py	New integration patching parse_request() to emit WEB_REQUEST_STARTING after successful parsing.
ddtrace/contrib/internal/http_server/init.py	New integration docstring describing the purpose and enabling/disabling behavior.
ddtrace/contrib/internal/flask/patch.py	Emits WEB_REQUEST_STARTING at the start of patched_wsgi_app().
ddtrace/contrib/internal/falcon/middleware.py	Emits WEB_REQUEST_STARTING at the start of Falcon process_request().
ddtrace/contrib/internal/django/response.py	Emits WEB_REQUEST_STARTING early in Django traced_get_response().
ddtrace/contrib/internal/cherrypy/patch.py	Emits WEB_REQUEST_STARTING at CherryPy _on_start_resource().
ddtrace/contrib/internal/bottle/trace.py	Adds a Bottle.wsgi wrapper emitting WEB_REQUEST_STARTING before routing.
ddtrace/contrib/internal/bottle/patch.py	Installs the new Bottle Bottle.wsgi wrapper.
ddtrace/contrib/internal/asgi/middleware.py	Emits WEB_REQUEST_STARTING for root-app HTTP requests before tracing context is created.
ddtrace/_monkey.py	Enables the new http_server integration by default and maps it to http.server.
.riot/requirements/43423a3.txt	Adds generated riot requirements lock for one environment set.
.riot/requirements/3cb8c3c.txt	Adds generated riot requirements lock for one environment set.
.riot/requirements/180047f.txt	Adds generated riot requirements lock for one environment set.
.riot/requirements/1638d0f.txt	Adds generated riot requirements lock for one environment set.
.riot/requirements/13ed954.txt	Adds generated riot requirements lock for one environment set.
.riot/requirements/1362718.txt	Adds generated riot requirements lock for one environment set.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[cit-pr-commenter-54b7da]

Codeowners resolved as

Resolved from the full PR diff against tianning.li/1-runtime-identity-refresh using the target branch CODEOWNERS file.
CODEOWNERS team requests not listed below are not required by the current file set.

ddtrace/contrib/internal/flask/patch.py                                 @DataDog/apm-core-python @DataDog/apm-idm-python
ddtrace/internal/core/__init__.py                                       @DataDog/apm-core-python
tests/contrib/flask/test_microvm_identity_refresh.py                    @DataDog/apm-core-python @DataDog/apm-idm-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.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.llmobs -> ddtrace.llmobs._evaluators -> ddtrace.llmobs._evaluators.format -> ddtrace.llmobs._experiment -> ddtrace.llmobs
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

[litianningdatadog]

Benchmarks

Benchmark execution time: 2026-08-20 10:43:42

Comparing candidate commit 2df658b in PR branch tianning.li/2-web-request-starting-event with baseline commit 2fa8088 in branch tianning.li/1-runtime-identity-refresh.

📊 Benchmarking dashboard

Found 0 performance improvements and 8 performance regressions! Performance is the same for 614 metrics, 10 unstable metrics.

Explanation

This is an A/B test comparing a candidate commit's performance against that of a baseline commit. Performance changes are noted in the tables below as:

• 🟩 = significantly better candidate vs. baseline
• 🟥 = significantly worse candidate vs. baseline

We compute a confidence interval (CI) over the relative difference of means between metrics from the candidate and baseline commits, considering the baseline as the reference.

If the CI is entirely outside the configured SIGNIFICANT_IMPACT_THRESHOLD (or the deprecated UNCONFIDENCE_THRESHOLD), the change is considered significant.

Feel free to reach out to #apm-benchmarking-platform on Slack if you have any questions.

More details about the CI and significant changes

You can imagine this CI as a range of values that is likely to contain the true difference of means between the candidate and baseline commits.

CIs of the difference of means are often centered around 0%, because often changes are not that big:

---------------------------------(------|---^--------)-------------------------------->
                              -0.6%    0%  0.3%     +1.2%
                                 |          |        |
         lower bound of the CI --'          |        |
sample mean (center of the CI) -------------'        |
         upper bound of the CI ----------------------'

As described above, a change is considered significant if the CI is entirely outside the configured SIGNIFICANT_IMPACT_THRESHOLD (or the deprecated UNCONFIDENCE_THRESHOLD).

For instance, for an execution time metric, this confidence interval indicates a significantly worse performance:

----------------------------------------|---------|---(---------^---------)---------->
                                       0%        1%  1.3%      2.2%      3.1%
                                                  |   |         |         |
       significant impact threshold --------------'   |         |         |
                      lower bound of CI --------------'         |         |
       sample mean (center of the CI) --------------------------'         |
                      upper bound of CI ----------------------------------'

scenario:httppropagationinject-ids_only

• 🟥 execution_time [+2.359µs; +2.544µs] or [+10.850%; +11.700%]

scenario:iast_aspects-re_expand_aspect

• 🟥 execution_time [+285.841µs; +324.440µs] or [+7.908%; +8.976%]

scenario:iastaspects-repr_aspect

• 🟥 execution_time [+74.200µs; +79.392µs] or [+19.846%; +21.235%]

scenario:iastaspectsospath-ospathbasename_aspect

• 🟥 execution_time [+132.794µs; +140.553µs] or [+32.640%; +34.547%]

scenario:iastaspectssplit-rsplit_aspect

• 🟥 execution_time [+16.606µs; +21.172µs] or [+11.659%; +14.865%]

scenario:span-start

• 🟥 execution_time [+1.227ms; +1.383ms] or [+8.092%; +9.119%]

scenario:telemetryaddmetric-1-count-metric-1-times

• 🟥 execution_time [+495.238ns; +539.209ns] or [+18.994%; +20.681%]

scenario:tracer-small

• 🟥 execution_time [+29.655µs; +32.469µs] or [+8.750%; +9.580%]

Unstable benchmarks

@pr-commenter I ran the benchmark test locally for scenario:iastaspectsospath-ospathbasename_aspect but the result doesn't show the regression.

Benchmark	Baseline	Candidate	Change
appsec_iast_aspects_ospath/ospathbasename_aspect	92.28 us ± 3.44 us	92.34 us ± 2.97 us	+0.06%

Interpretation

Benchmark	Change	Signal	Stddev overlap
appsec_iast_aspects_ospath/ospathbasename_aspect	+0.06%	noise	yes

Signals use the local guide thresholds: <2% is noise, 2-5% is small, and >5% regression should be investigated. Stddev overlap marks results that may need a rerun before drawing conclusions.

[brettlangdon]

it seems like http.server is a whole new integration, we should not bundle these together.

[litianningdatadog]

it seems like http.server is a whole new integration, we should not bundle these together.

@brettlangdon Will do

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4e7094825c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[dubloom]

I'm not sure about the goal of this PR. There is already an existing web.request.start event. Can't we use this one ?

Additionally, right now, nothing is listening to this event so it is a bit hard to justify a full PR because it would mean we merge a noop/just overhead

[dubloom]

This is not the right place to define an event

[litianningdatadog]

acked, it was moved to web_framework.py as i saw WEB_REQUEST defined there.

[litianningdatadog]

Renamed the branch to tianning.li/2-flask-web-request-starting-event; GitHub closed this PR when the old head ref disappeared. Replacement PR: #19816.