Add Live Debugger package by watson · Pull Request #4449 · DataDog/browser-sdk

watson · 2026-04-07T08:51:33Z

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

Unit tests: yarn test:unit --spec "packages/debugger/src/**/*.spec.ts"
E2E tests: yarn test:e2e:init && yarn test:e2e -g "debugger"
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 · 2026-04-07T08:51:45Z

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

watson · 2026-04-07T08:51:49Z

Add Live Debugger package #4449 : 6 dependent PRs (#4480 , #4503 , #4508 and 3 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 · 2026-04-07T08:54:03Z

🎉 All green!

❄️ No new flaky tests detected
🧪 All tests passed

🎯 Code Coverage (details)
• Patch Coverage: 71.94%
• Overall Coverage: 76.69% (-0.32%)

_{This comment will be updated automatically if new data arrives.

🔗 Commit SHA: 8130067 | Docs | Datadog PR Page | Give us feedback!}

cit-pr-commenter-54b7da · 2026-04-07T13:32:57Z

Bundles Sizes Evolution

📦 Bundle Name	Base Size	Local Size	𝚫	𝚫%	Status
Rum	N/A	179.42 KiB	N/A	N/A	N/A
Rum Profiler	N/A	6.16 KiB	N/A	N/A	N/A
Rum Recorder	N/A	27.03 KiB	N/A	N/A	N/A
Logs	N/A	56.80 KiB	N/A	N/A	N/A
Rum Slim	N/A	135.26 KiB	N/A	N/A	N/A
Worker	N/A	23.63 KiB	N/A	N/A	N/A

🚀 CPU Performance

Action Name	Base CPU Time (ms)	Local CPU Time (ms)	𝚫%
addglobalcontext	N/A	0.0049	N/A
addaction	N/A	0.0136	N/A
adderror	N/A	0.013	N/A
addtiming	N/A	0.0028	N/A
startview	N/A	0.0124	N/A
startstopsessionreplayrecording	N/A	0.0007	N/A
logmessage	N/A	0.0145	N/A

🧠 Memory Performance

Action Name	Base Memory Consumption	Local Memory Consumption	𝚫
addglobalcontext	N/A	31.53 KiB	N/A
addaction	N/A	101.84 KiB	N/A
addtiming	N/A	32.46 KiB	N/A
adderror	N/A	104.34 KiB	N/A
startstopsessionreplayrecording	N/A	32.01 KiB	N/A
startview	N/A	489.22 KiB	N/A
logmessage	N/A	99.21 KiB	N/A

🔗 RealWorld

watson · 2026-04-07T13:46:31Z

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

Introduce the browser debugger SDK and probe execution pipeline so browser code can evaluate conditions, capture snapshots, and render probe messages at runtime. Add Delivery API polling plus sandbox and performance tooling to support probe delivery and testing.

mormubis

I'd get another approval before merging. We usually look for at least two approvals.

thomas-lebeau · 2026-04-22T18:49:20Z

+function toSdkSource(source: TransportConfiguration['source']): SdkSource {
+  return source === 'dd_debugger' ? 'browser' : source
+}


❓ question: ‏why setting the source to dd_debugger to set it back to browser later?

I think we should keep dd_debugger (or just debugger for consistency) and your team should maintain their own monitors, dashboards, ...

thomas-lebeau · 2026-04-22T18:56:55Z

    DD_LOGS?: LogsGlobal
    DD_RUM?: RumGlobal
+    DD_DEBUGGER?: DebuggerPublicApi


💬 suggestion: the types LogsGlobal and RumGlobal are deprecated in favor of DatadogLogs and DatadogRum. what about using DatadogDebugger for consistency?

thomas-lebeau · 2026-04-23T05:44:58Z

+})
+```
+
+If [Datadog RUM][3] is also initialized on the page, debugger snapshots automatically include RUM context (session, view, user action) without any additional configuration.


❓ question: ‏How does this works? I must have missed something, I didn't see how this sdk collects sessions

I think the text here should probably be slightly modified to read better, but the gist is that we tie the probe result to the current trace/span: https://github.com/DataDog/browser-sdk/pull/4449/files#diff-88cda10a3adeb04ab7401bf422650f85908ff2261c31b4411959b7c80be817d4R330-R341

🤔 these fields (traceId and spanId) don't exist in RumInternalContext, is it really working?

Ha interesting. I was actually looking for ways I could test this in an integration test without mocking it, but couldn't find a good way to do it, so I settled for a unit test after my AI had added it. Turns out my gut feeling was correct that this needed better testing

We use session.id to correlate RUM event with logs, profiles and session replay.

Use the existing debugger service configuration when polling for probes so browser callers keep sending a valid delivery identity after the applicationId rollback. This also removes the stale applicationId init examples and test fixtures from the debugger package. Made-with: Cursor

BenoitZugmeyer · 2026-05-04T10:59:47Z

+  const rumContext = globalObj.DD_RUM?.getInternalContext?.()
+  const traceId = getStringContextValue(rumContext, 'trace_id')
+  const spanId = getStringContextValue(rumContext, 'span_id')
+
+  return traceId && spanId
+    ? {
+        trace_id: traceId,
+        span_id: spanId,
+      }
+    : undefined


issue: trace_id and span_id don't exist in getInternalContext

BenoitZugmeyer · 2026-05-04T11:00:30Z

+const hasReplaceAll = typeof (String.prototype as any).replaceAll === 'function'
+const replaceDots = hasReplaceAll
+  ? (str: string) => (str as string & { replaceAll: (s: string, r: string) => string }).replaceAll('.', '_')
+  : (str: string) => str.replace(/\./g, '_')


Suggested change

const hasReplaceAll = typeof (String.prototype as any).replaceAll === 'function'

const replaceDots = hasReplaceAll

? (str: string) => (str as string & { replaceAll: (s: string, r: string) => string }).replaceAll('.', '_')

: (str: string) => str.replace(/\./g, '_')

const replaceDots = (str: string) => str.replace(/\./g, '_')

BenoitZugmeyer · 2026-05-04T11:08:43Z

+      let fn = functionCache.get(cacheKey)
+      if (!fn) {
+        // eslint-disable-next-line no-new-func, @typescript-eslint/no-implied-eval
+        fn = new Function(...contextKeys, fnBody) as (...args: any[]) => boolean


issue: eval is evil, we shouldn't rely on eval if possible. Best practice is often to use CSP that block such functionality.

Is there something specific in the language that requires "inline" JavaScript code? Else we can probably parse its AST and run it using JS without actually generating JS code.

BenoitZugmeyer · 2026-05-04T12:00:32Z

+
+declare const __BUILD_ENV__SDK_VERSION__: string
+
+const DELIVERY_API_PATH = '/api/ui/debugger/probe-delivery'


Question: what is this route? Is this supposed to live on the customer website?

BenoitZugmeyer · 2026-05-04T12:05:54Z

+  "name": "@datadog/browser-debugger",
+  "version": "6.32.0",


suggestion:: mark this as "private": true so we don't publish it until it's ready for customer consumpiton

BenoitZugmeyer · 2026-05-04T12:14:36Z

+    ;(window as any).USE_INSTRUMENTED = true
+  })
+
+  // Load debugger SDK (using local build for now)


question: why not using the actual SDK?

BenoitZugmeyer · 2026-05-04T12:16:43Z

+  createTest('send debugger snapshot when instrumented function is called')
+    .withDebugger()
+    .run(async ({ intakeRegistry, flushEvents, page, browserName, servers }) => {
+      test.skip(browserName !== 'chromium', 'Debugger tests require Chromium')


question why debugger tests require Chromium?

BenoitZugmeyer · 2026-05-04T12:22:21Z

  }
 }

+async function readDebuggerIntakeRequest(


suggestion: this is a copy of the readRumOrLogsIntakeRequest function. You can just re-use it

watson force-pushed the watson/DEBUG-5296/add-live-debugger branch from 4df303f to b539c14 Compare April 7, 2026 13:30

watson force-pushed the watson/DEBUG-5296/add-live-debugger branch 6 times, most recently from 3042bfe to 98490f7 Compare April 7, 2026 15:45

watson marked this pull request as ready for review April 7, 2026 15:56

watson requested a review from a team as a code owner April 7, 2026 15:56

allspain mentioned this pull request Apr 7, 2026

Shadow: Add Live Debugger package (v1) allspain/browser-sdk-shadow-reviews#11

Open

4 tasks

chatgpt-codex-connector Bot reviewed Apr 7, 2026

View reviewed changes

Comment thread packages/debugger/src/domain/capture.ts Outdated

Comment thread packages/debugger/src/domain/api.ts Outdated

watson force-pushed the watson/DEBUG-5296/add-live-debugger branch 4 times, most recently from 9bbedbf to bf9a162 Compare April 14, 2026 10:30

This was referenced Apr 14, 2026

Switch debugger delivery to public ClientTokenAuth endpoint #4480

Draft

Document optional browser debugger version #4503

Closed

Tighten Live Debugger global hook typing #4508

Draft

Make Live Debugger per-second budgets configurable #4509

Draft

This was referenced Apr 21, 2026

Add Live Debugger lifetime event budgets #4510

Draft

Default debugger version and embed build identity in snapshots #4511

Draft

[Live Debugger] Add 10ms snapshot capture timeout circuit breaker #4512

Draft

watson force-pushed the watson/DEBUG-5296/add-live-debugger branch from bf9a162 to b9da4f3 Compare April 21, 2026 07:36

watson changed the base branch from main to graphite-base/4449 April 21, 2026 08:17

watson force-pushed the watson/DEBUG-5296/add-live-debugger branch from b9da4f3 to 0040ee8 Compare April 21, 2026 08:17

watson changed the base branch from graphite-base/4449 to watson/DEBUG-5296/fix-lint April 21, 2026 08:17

watson mentioned this pull request Apr 21, 2026

Fix TanStack Router lint resolution in test app #4513

Merged

5 tasks

Base automatically changed from watson/DEBUG-5296/fix-lint to main April 21, 2026 09:11

watson force-pushed the watson/DEBUG-5296/add-live-debugger branch from 0040ee8 to 653aee9 Compare April 21, 2026 09:13

mormubis reviewed Apr 22, 2026

View reviewed changes

Comment thread packages/debugger/src/domain/api.ts Outdated

Comment thread packages/debugger/src/domain/stacktrace.ts

watson requested a review from mormubis April 22, 2026 12:25

watson force-pushed the watson/DEBUG-5296/add-live-debugger branch 2 times, most recently from a90f65e to 43903ba Compare April 22, 2026 12:47

watson added 3 commits April 22, 2026 15:48

Fix trace correlation

3f4bdd3

Use existing stack trace logic

7d1efe7

watson force-pushed the watson/DEBUG-5296/add-live-debugger branch from 43903ba to 7d1efe7 Compare April 22, 2026 14:24

mormubis approved these changes Apr 22, 2026

View reviewed changes

thomas-lebeau reviewed Apr 23, 2026

View reviewed changes

BenoitZugmeyer reviewed May 4, 2026

View reviewed changes


		declare const __BUILD_ENV__SDK_VERSION__: string

		const DELIVERY_API_PATH = '/api/ui/debugger/probe-delivery'

Conversation

watson commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Changes

New package: packages/debugger

Changes to @datadog/browser-core

E2E test framework and scenarios

Performance benchmarks

Tooling

Test instructions

Checklist

Uh oh!

github-actions Bot commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

watson commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

datadog-datadog-prod-us1 Bot commented Apr 7, 2026 • edited by datadog-prod-us1-5 Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cit-pr-commenter-54b7da Bot commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundles Sizes Evolution

Uh oh!

watson commented Apr 7, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mormubis left a comment

Choose a reason for hiding this comment

Uh oh!

thomas-lebeau Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

watson commented Apr 7, 2026 •

edited

Loading

New package: `packages/debugger`

Changes to `@datadog/browser-core`

github-actions Bot commented Apr 7, 2026 •

edited

Loading

watson commented Apr 7, 2026 •

edited

Loading

datadog-datadog-prod-us1 Bot commented Apr 7, 2026 •

edited by datadog-prod-us1-5 Bot

Loading

cit-pr-commenter-54b7da Bot commented Apr 7, 2026 •

edited

Loading

thomas-lebeau Apr 22, 2026 •

edited

Loading