Add Live Debugger package

[watson]

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

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[watson]

• Add Live Debugger package #4449 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[datadog-datadog-prod-us1]

✅ Tests

🎉 All green!

❄️ No new flaky tests detected
🧪 All tests passed

🎯 Code Coverage (details)
• Patch Coverage: 72.09%
• Overall Coverage: 77.22% (-0.39%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: c43480d | Docs | Datadog PR Page | Was this helpful? React with 👍/👎 or give us feedback!}

[cit-pr-commenter-54b7da]

Bundles Sizes Evolution

📦 Bundle Name	Base Size	Local Size	𝚫	𝚫%	Status
Rum	177.94 KiB	178.09 KiB	+157 B	+0.09%	✅
Rum Profiler	6.16 KiB	6.16 KiB	0 B	0.00%	✅
Rum Recorder	27.03 KiB	27.03 KiB	0 B	0.00%	✅
Logs	56.40 KiB	56.55 KiB	+157 B	+0.27%	✅
Rum Slim	133.81 KiB	133.96 KiB	+157 B	+0.11%	✅
Worker	23.63 KiB	23.63 KiB	0 B	0.00%	✅

🚀 CPU Performance

Action Name	Base CPU Time (ms)	Local CPU Time (ms)	𝚫%
RUM - add global context	0.0085	0.0064	-24.71%
RUM - add action	0.0264	0.0209	-20.83%
RUM - add error	0.0247	0.0198	-19.84%
RUM - add timing	0.0053	0.0038	-28.30%
RUM - start view	0.0233	0.0157	-32.62%
Logs - log message	0.0306	0.0257	-16.01%

🧠 Memory Performance

Action Name	Base Memory Consumption	Local Memory Consumption	𝚫
RUM - add global context	25.97 KiB	27.77 KiB	+1.80 KiB
RUM - add action	98.72 KiB	93.20 KiB	-5.52 KiB
RUM - add timing	26.43 KiB	25.43 KiB	-1020 B
RUM - add error	85.28 KiB	94.59 KiB	+9.31 KiB
RUM - start/stop session replay recording	26.30 KiB	25.52 KiB	-793 B
RUM - start view	486.03 KiB	484.07 KiB	-1.96 KiB
Logs - log message	92.85 KiB	98.34 KiB	+5.50 KiB

🔗 RealWorld

[watson]

I have read the CLA Document and I hereby sign the CLA

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 98490f775f

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