Shadow: Add Live Debugger package (v2)

[allspain]

Shadow Review — PR DataDog#4449 v2

Source: DataDog#4449
Commit: 98548d4e33863d2ec03b14668ea76010d2e814c0
Timestamp: 2026-04-07T19:13:47Z

---

Original PR Description

Motivation

Introduce the @datadog/browser-debugger package to enable Live Debugger in browser applications. This gives frontend developers the ability to add log probes to running applications, evaluate conditions, and inspect runtime state — all without redeploying or modifying source code.

Note: This package is intended for internal Datadog use only until validated in production. It follows the same convention as @datadog/browser-core, @datadog/browser-rum-core, and @datadog/browser-worker — published to npm with each release (to keep versions in sync), but excluded from generated documentation via typedoc.json.

Changes

New package: packages/debugger

A new @datadog/browser-debugger package that provides the full probe execution pipeline:

• domain/api.ts — Core instrumentation hooks (onEntry, onReturn, onThrow) that execute probes when instrumented functions are called, including condition evaluation, snapshot capture, template message rendering, and rate limiting.
• domain/activeEntries.ts — Tracks per-probe execution stacks for correlating entry/return/throw events, extracted to break the dependency cycle between api.ts and probes.ts.
• domain/probes.ts — Probe lifecycle management (add, remove, clear) with per-probe and global snapshot rate limiting. Compiles probe conditions and template segments on registration.
• domain/capture.ts — Deep value capture for arguments, locals, return values, and thrown errors with configurable reference depth, collection size limits, and string length limits.
• domain/expression.ts — Expression compiler that parses JSON expression trees (comparisons, logical operators, member access, string operations, etc.) into executable functions.
• domain/condition.ts — Probe condition evaluator that compiles and caches condition expressions.
• domain/template.ts — Template segment compiler and evaluator for rendering dynamic probe messages with runtime context.
• domain/stacktrace.ts — Stack trace capture and parsing from Error objects.
• domain/deliveryApi.ts — Polling-based probe delivery client that fetches probe updates/deletions from the Delivery API using a cursor for incremental sync.
• transport/startDebuggerBatch.ts — Transport layer that reuses @datadog/browser-core's batch/flush infrastructure to send debugger snapshots to the logs intake.
• entries/main.ts — Public API surface (datadogDebugger.init()). Exposes $dd_entry/$dd_return/$dd_throw/$dd_probes hooks on globalThis for instrumented code. Defines the global DD_DEBUGGER object.

Changes to @datadog/browser-core

• Added 'dd_debugger' as a valid source in configuration and transport types, mapped to 'browser' for the SDK source.
• Exported computeTransportConfiguration and the Batch type so the debugger package can create its own transport.

E2E test framework and scenarios

• test/e2e/scenario/debugger.scenario.ts — 7 E2E test scenarios covering: basic snapshot sending, argument/return value capture, exception capture on throw, template message evaluation with expression segments, condition evaluation (both met and not met), and RUM correlation.
• E2E framework extensions — Added .withDebugger() builder method to createTest(), DebuggerIntakeRequest type and intakeRegistry.debuggerEvents for asserting on debugger events, debugger page setups for CDN/bundle/npm modes, and default debugger configuration.
• test/apps/vanilla/app.ts — Added @datadog/browser-debugger import and DEBUGGER_INIT support so debugger E2E tests work in the npm setup.

Performance benchmarks

• test/apps/instrumentation-overhead/ — Webpack test app for measuring instrumentation overhead with instrumented vs. uninstrumented function variants.
• test/performance/scenarios/instrumentationOverhead.scenario.ts — Benchmark scenario that stress-tests 10M function calls to measure the overhead of debugger instrumentation hooks.
• test/performance/createBenchmarkTest.ts — Extended with instrumented_no_probes and instrumented_with_probes scenario configurations and a dedicated injectDebugger function.

Tooling

• Updated scripts/build/build-test-apps.ts to include the new test app and to use resolution paths when installing peer dependencies (needed for unpublished packages like @datadog/browser-debugger that only exist locally as .tgz files).
• Updated scripts/dev-server/lib/server.ts to serve the debugger bundle.
• Added debugger entry point to ESLint side-effects allowlist.

Test instructions

1. Unit tests: yarn test:unit --spec "packages/debugger/src/**/*.spec.ts"
2. E2E tests: yarn test:e2e:init && yarn test:e2e -g "debugger"
3. Performance testing: yarn build:apps && yarn test:performance

Checklist

• Tested locally
• Tested on staging — N/A, this is a new pre-production package not yet deployed to any environment
• Added unit tests for this change.
• Added e2e/integration tests for this change.
• Updated documentation and/or relevant AGENTS.md file