chore(serverless): publish web request-start event

[litianningdatadog]

Stacked PRs:

• chore(runtime): add explicit identity refresh #19778 — runtime identity foundation
  • This PR chore(serverless): publish web request-start event #19898 — generic WSGI/ASGI/Django request-start event
    • chore(runtime): refresh MicroVM identity #19939 — MicroVM request-start listener and identity refresh
      • fix(tracer): isolate MicroVM identity refresh #19820 — tracer/native writer exporter refresh
        • fix(telemetry): rebuild worker on identity refresh #19821 — telemetry worker refresh
          • chore(runtime): refresh runtime metric identity and collector state #19822 — runtime-metrics runtime-ID tags

Description

This PR provides the framework side of the MicroVM identity-refresh flow. WSGI,
ASGI, and Django publish web.request.starting before they create a root span,
passing the request method and normalized path.

The publisher is deliberately product-neutral: it does not import MicroVM
helpers, recognize the MicroVM /run endpoint, or decide whether to refresh a
runtime ID. PR #19939 registers the MicroVM-only listener and owns that policy.
When no product listens for the event, the publisher returns after a single
listener check, before reading the request or normalizing the path.

Two helpers in trace_utils own the publishing:

• dispatch_wsgi_web_request_starting(environ) is used by DDWSGIMiddleware
  and Django's get_response hook. WSGI and Django share an environ marker so
  nested layers publish one event. The Django hook also covers Django 3.0 ASGI
  requests, which reach the sync get_response because get_asgi_application
  is only wrapped on Django 3.1+.
• dispatch_asgi_web_request_starting(scope) publishes only from the outer ASGI
  application. It accepts scopes whether or not path already includes
  root_path, so mounted or server-prefixed apps do not produce a duplicated
  prefix.

Scope: the event is published for the generic WSGI/ASGI middleware and Django.
Frameworks whose automatic instrumentation creates the root span without
DDWSGIMiddleware (Falcon, Bottle, Pyramid, CherryPy, Molten) are out of scope
for this PR and will follow separately.

This implements the requested split in review comment r4146791727.

Reference

• RFC

Testing

• scripts/lint fmt and scripts/lint typing on the changed files
• focused WSGI request-start tests (py3.13): 7 passed
• focused ASGI request-start tests (py3.13): 48 passed
• focused Django request-start tests: 3 passed on Django 3.0 (py3.9) and on
  Django 5.1 (py3.13), including a real ASGIRequest reaching get_response

Risks

There is no public API change. The only production listener in this stack is
registered by PR #19939 in MicroVM processes, so non-MicroVM requests do not
dispatch this event.

🤖 Generated with Claude Code

[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.

No remaining files require a CODEOWNERS review.

[cit-pr-commenter-54b7da]

Circular import analysis

⚠️ Existing circular imports

There are 1 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

[cit-pr-commenter-54b7da]

Dependency direction analysis

⚠️ Existing dependency direction violations

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

Show existing violations (showing 5 of 191 highest severity)

ddtrace.internal.tracemethods -×-> ddtrace.trace  (internal-core -> product:tracing, score=125)
ddtrace.internal.openfeature._span_enrichment -×-> ddtrace.trace  (product:openfeature -> product:tracing, score=123)
ddtrace.internal.ci_visibility.recorder -×-> ddtrace.trace  (product:ci_visibility -> product:tracing, score=123)
ddtrace.llmobs._integrations.vllm -×-> ddtrace.trace  (product:llmobs -> product:tracing, score=123)
ddtrace.llmobs._integrations.openai_agents -×-> ddtrace.trace  (product:llmobs -> product:tracing, score=123)

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-us1-prod]

✅ All CI checks and tests passed.

🎉 All green!

🧪 All tests passed
❄️ No new flaky tests detected

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 1e76b73 | Docs | View more details | Give us feedback!}

[Copilot]

🟡 Changes recommended

The environment detector lacks direct coverage, and the release note announces behavior completed only by a follow-up PR.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds pre-span MicroVM request detection to WSGI and ASGI instrumentation, supporting the runtime identity refresh stack.

Changes:

• Dispatches web.request.starting for matching MicroVM requests.
• Adds explicit runtime identity refresh callbacks while preserving fork lineage.
• Adds focused integration/runtime tests and a release note.

File summaries

File	Description
ddtrace/contrib/_events/web_framework.py	Defines the request-start event.
ddtrace/contrib/internal/web.py	Matches and dispatches MicroVM requests.
ddtrace/contrib/internal/asgi/middleware.py	Dispatches before ASGI span creation.
ddtrace/contrib/internal/wsgi/wsgi.py	Dispatches before WSGI span creation.
ddtrace/internal/serverless/__init__.py	Detects the MicroVM environment.
ddtrace/internal/runtime/__init__.py	Adds explicit identity refresh support.
tests/contrib/asgi/test_asgi.py	Tests ASGI matching and ordering.
tests/contrib/wsgi/test_wsgi.py	Tests WSGI request matching.
tests/tracer/runtime/test_runtime_id.py	Tests refresh and fork semantics.
releasenotes/notes/add-lambda-microvm-web-request-starting-ffa6841a15e3c57c.yaml	Announces MicroVM request detection.

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 2
• Review effort level: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[lym953]

Approving blindly as I don't have knowledge on any of the files, and since apm-serverless has approved it.
Will discuss whether we should remove serverless-aws as owner.

[quinna-h]

LGTM overall for the test files that IDM owns; left one comment about a test that was supposed to prove the request-start event happens before the request span is created, but instead the span marker records when the middleware retrieves the span

[avara1986]

LGTM

[dubloom]

Some small comments but overall LGTM

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 11ab2d5fe7

ℹ️ 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".

[litianningdatadog]

/merge

[gh-worker-devflow-routing-ef8351]

View all feedbacks in Devflow UI.

2026-10-08 15:20:55 UTC ℹ️ Start processing command /merge

---

2026-10-08 15:21:00 UTC ℹ️ MergeQueue: pull request added to the queue

The expected merge time in main is approximately 57m (p90).

---

2026-10-08 16:24:07 UTC ℹ️ MergeQueue: This merge request was merged