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 : 5 dependent PRs (#4480 , #4503 , #4508 and 2 others) 👈 (View in Graphite)
• Fix TanStack Router lint resolution in test app #4513
• main

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

[datadog-datadog-prod-us1]

🎉 All green!

❄️ No new flaky tests detected
🧪 All tests passed

🎯 Code Coverage (details)
• Patch Coverage: 72.33%
• Overall Coverage: 76.70% (-0.31%)

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

[cit-pr-commenter-54b7da]

Bundles Sizes Evolution

📦 Bundle Name	Base Size	Local Size	𝚫	𝚫%	Status
Rum	179.65 KiB	179.69 KiB	+40 B	+0.02%	✅
Rum Profiler	6.17 KiB	6.17 KiB	0 B	0.00%	✅
Rum Recorder	27.03 KiB	27.03 KiB	0 B	0.00%	✅
Logs	56.78 KiB	56.82 KiB	+40 B	+0.07%	✅
Rum Slim	135.50 KiB	135.54 KiB	+40 B	+0.03%	✅
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.0039	0.004	+2.56%
RUM - add action	0.0131	0.0133	+1.53%
RUM - add error	0.0117	0.0131	+11.97%
RUM - add timing	0.0025	0.0026	+4.00%
RUM - start view	0.0119	0.014	+17.65%
RUM - start/stop session replay recording	0.0006	0.0008	+33.33%
Logs - log message	0.0138	0.0189	+36.96%

🧠 Memory Performance

Action Name	Base Memory Consumption	Local Memory Consumption	𝚫
RUM - add global context	31.78 KiB	30.51 KiB	-1.27 KiB
RUM - add action	56.94 KiB	55.55 KiB	-1.40 KiB
RUM - add timing	32.72 KiB	33.15 KiB	+436 B
RUM - add error	60.80 KiB	59.38 KiB	-1.42 KiB
RUM - start/stop session replay recording	32.10 KiB	32.39 KiB	+290 B
RUM - start view	484.29 KiB	482.94 KiB	-1.36 KiB
Logs - log message	95.66 KiB	91.44 KiB	-4.22 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".