Reduce Node Lambda cold-start overhead with synchronous ESM loader hooks

[lucaspimentel]

What does this PR do?

Install dd-trace's ESM instrumentation hooks in-thread on supported Node versions instead of starting a background loader worker during Lambda initialization.

• Load dd-trace's loader hook through dynamic import(), then register its synchronous hooks before loading the user handler.
• Keep the existing asynchronous registration path on unsupported Node versions, when the hook cannot be imported, or when synchronous registration is unavailable.
• If synchronous registration throws, avoid also installing the asynchronous loader: hooks may already be installed, and a second registration could instrument modules twice.

Motivation

The ESM loader registration added in #801 (layer v12.142.0) increased Node Lambda cold-start overhead. #819 (v12.143.0) reduced that overhead, but the Lambda bootstrap still launches Node with --no-experimental-require-module by default. This prevents dd-trace's registration entry point from reaching its synchronous hooks through require(esm), so it falls back to the background loader worker.

Dynamic import() is unaffected by that flag and allows the synchronous hooks to be installed directly.

A local AWS Lambda RIE benchmark of the committed change, using Node 24.21.0 and dd-trace 6.15.0, showed:

Handler	Baseline median init	Fixed median init	Saved
CJS	171.8 ms	118.9 ms	52.9 ms (30.8%)
ESM	278.3 ms	218.7 ms	59.6 ms (21.4%)

Both variants used the same layer and fixtures, with fresh containers and interleaved, alternating run order. These are local RIE/WSL measurements, not deployed Lambda latency estimates. The ESM fixture's 100 ms top-level-await delay was unchanged.

Testing Guidelines

• The full Jest suite passes on Node 26.10.0 and Node 22.20.0, run with --runInBand.
• Published-handler tests verify synchronous registration on Node 26 and asynchronous fallback on Node 22.20 under --no-experimental-require-module, while preserving durable execution spans.
• Unit tests cover version gating, missing registration APIs, preloaded hooks, import failure, unavailable synchronous registration, and synchronous-registration throws without fallback.
• Lint, the repository formatting check, and git diff --check pass.
• Separate RIE diagnostic invocations confirmed the baseline uses the asynchronous registration API and the fix uses the synchronous API. All measured CJS and ESM invocations returned the expected response.

Additional Notes

• Synchronous hooks require Node 22.22.3+, 24.11.1+, 25.1+, or 26+, within their respective major-version lines, and the synchronous registration API must exist. The local version gate mirrors dd-trace's gate.
• Registration diagnostics use debug logging only.
• The full local integration matrix and deployed AWS Lambda latency validation have not been run.

Types of Changes

• Bug fix
• New feature
• Breaking change
• Misc (docs, refactoring, dependency upgrade, etc.)

Check all that apply

• This PR's description is comprehensive
• This PR contains breaking changes that are documented in the description
• This PR introduces new APIs or parameters that are documented and unlikely to change in the foreseeable future
• This PR impacts documentation, and it has been updated (or a ticket has been logged)
• This PR's changes are covered by the automated tests
• This PR collects user input/sensitive content into Datadog
• This PR passes the integration tests (ask a Datadog member to run the tests)

[lucaspimentel]

@DataDog review

[datadog-datadog-prod-us1-2]

More details

The registration paths preserve hook installation before handler loading, including asynchronous fallback when synchronous hooks are unavailable. The completed static review found no reportable regression.

Was this helpful? React 👍 or 👎

_{Open Bits AI session}

_{🤖 Bits Code Review · Commit f1bf76b · @DataDog review to ask questions}