fix(django): don't force ROOT_URLCONF import during django.setup()

[christophe-papazian]

APPSEC-69515

Description

Alternative to #19465 for the same regression (#19454). Endpoint discovery walked the root resolver at the end of
traced_populate, so django.setup() imported ROOT_URLCONF and every view module behind it — 154 MB of RSS per
dramatiq worker that serves no requests. The eager call arrived in #17695, so every release from 4.9.0rc1 is affected.

This moves the walk to traced_load_middleware: building a BaseHandler is the earliest reliable signal that a
process will serve HTTP, so workers pay nothing while gunicorn/uwsgi/daphne still report endpoints at startup.
BaseHandler.load_middleware is now wrapped unconditionally so discovery no longer depends on
DD_DJANGO_INSTRUMENT_MIDDLEWARE.

#19465 instead guards the walk on ROOT_URLCONF already being in sys.modules, but Django imports the URLconf
neither during django.setup() nor during WSGIHandler.__init__ — only at the first resolve(). Measured with
get_wsgi_application(), which is what gunicorn imports:

	urlconf imported	endpoints at startup
main	yes	32
#19465	no	0
this PR	yes	32

Also adds '@django' and '@flask' to the telemetry suite in suitespec, which runs real apps of both but was
gated only on shared contrib infrastructure — which is why #19465's CI is green while it deterministically fails
test_endpoint_discovery_event.

Testing

test_setup_does_not_import_root_urlconf and test_endpoint_discovery_skipped_without_http_handler fail on main
and pass here. test_endpoint_discovery_event now builds the WSGI application and still passes (it fails on #19465).
test_wsgi_application_collects_endpoints pins #17695's include/test/ prefix joining at startup, and a paired test
pins that discovery survives DD_DJANGO_INSTRUMENT_MIDDLEWARE=false while middleware wrapping does not.

On a bare django.setup() (py3.13 / django 5.1): sys.modules 1243 → 1220, live GC objects 109,218 → 106,123, max
RSS 82,884 → 81,496 KB. Small here only because the test app's view closure is small — the delta is that closure.

contrib::django passes except 5 test_django_appsec_snapshots.py failures that reproduce identically on main.

Risks

Serving processes import the URLconf when the handler is built rather than on the first request — earlier than Django
would, but later and safer than the previous Apps.populate timing. Processes that build no handler no longer report
endpoints, which is the point. Management commands are unaffected either way: Django's own check_url_config imports
the URLconf whenever system checks run.

Additional Notes

Pre-existing and out of scope: _collect_routes_once marks a resolver collected in its finally block even when the
walk raised; the wsgi, appsec_integrations_django and ddtracerun suites have the same suitespec gap. ASGI
collection is reasoned but untested.

🤖 Generated with Claude Code

Credit to @bellini666 for diagnosing the regression and for test_setup_does_not_import_root_urlconf, carried over
from #19465.

[cit-pr-commenter-54b7da]

Codeowners resolved as

ddtrace/contrib/internal/django/patch.py                                @DataDog/apm-core-python @DataDog/apm-idm-python
releasenotes/notes/fix-django-eager-urlconf-import-aa3eff2dd008ec0f.yaml  @DataDog/apm-python
tests/contrib/django/test_django_patch.py                               @DataDog/apm-core-python @DataDog/apm-idm-python
tests/suitespec.yml                                                     @DataDog/python-guild @DataDog/apm-core-python
tests/telemetry/test_writer.py                                          @DataDog/apm-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.trace -> ddtrace._trace.tracer -> ddtrace.internal.debug -> ddtrace.trace
ddtrace -> ddtrace.trace -> ddtrace._trace.tracer -> ddtrace.internal.debug -> ddtrace
ddtrace -> ddtrace.trace -> ddtrace._trace.tracer -> ddtrace.internal.debug -> ddtrace.internal.runtime.runtime_metrics -> ddtrace

[pr-commenter]

Benchmarks

Benchmark execution time: 2026-08-04 13:35:09

Comparing candidate commit ffbd66d in PR branch christophe-papazian/django-lazy-endpoint-discovery with baseline commit 11c2498 in branch main.

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

scenario:httppropagationinject-ids_only

• 🟥 execution_time [+1.489µs; +1.622µs] or [+7.047%; +7.677%]

scenario:iastaspects-upper_aspect

• 🟥 execution_time [+58.393µs; +65.217µs] or [+19.440%; +21.712%]

scenario:iastaspectsospath-ospathbasename_aspect

• 🟥 execution_time [+99.922µs; +105.592µs] or [+24.752%; +26.156%]

scenario:span-start

• 🟥 execution_time [+1.484ms; +1.663ms] or [+9.339%; +10.466%]

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

• 🟥 execution_time [+206.452ns; +240.601ns] or [+9.837%; +11.464%]

scenario:tracer-small

• 🟥 execution_time [+31.814µs; +33.882µs] or [+9.489%; +10.106%]

[datadog-datadog-prod-us1]

🎉 All green!

🧪 All tests passed
❄️ No new flaky tests detected

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: ffbd66d | Docs | Datadog PR Page | Give us feedback!}