Add Live Debugger package (#4449)

Introduce the `@datadog/browser-debugger` package, which provides Live
Debugger support in browser applications. Frontend developers can attach
log probes to running applications, evaluate conditions, and inspect
runtime state without redeploying or modifying source code.

The package is published privately for now (excluded from generated docs
via `typedoc.json`).

The probe execution pipeline lives entirely on the client: instrumented
code calls into hooks exposed on `globalThis` (`$dd_entry`,
`$dd_return`, `$dd_throw`, `$dd_probes`), and the SDK is responsible
for evaluating probe conditions, capturing snapshots of arguments,
locals, return values, and thrown errors, rendering template messages
against runtime context, applying per-probe and global rate limits, and
shipping the resulting events to the logs intake. To keep that hot path
predictable, expressions, conditions, and message templates are
compiled once at probe registration and the capture logic enforces
explicit depth, collection-size, and string-length bounds.

Probes themselves are pulled from a Delivery API via a cursor-based
polling client, so probe lifecycle (add/remove/clear) is driven by the
backend rather than the page. Event delivery reuses
`@datadog/browser-core`'s batch/flush transport infrastructure, which
required a small core change: the transport layer now accepts
`'dd_debugger'` as a URL-only source override so events route correctly
in the intake without widening the public RUM `source` surface.

To validate behavior and guard against regressions, the change also
introduces E2E scenarios covering snapshot delivery, value capture,
exception handling, template and condition evaluation, and RUM
correlation, plus a dedicated instrumentation-overhead benchmark that
stress-tests the hooks against the real built bundle (rather than
stubs) so the per-call cost we track is the cost customers will
actually pay.

Author: watson

.github/CODEOWNERS

@@ -12,3 +12,10 @@ test/e2e/scenario/recorder/**                   @Datadog/rum-browser @Datadog/se
 
 # Docs
 /README.md    @Datadog/rum-browser @DataDog/documentation
+
+# Debugger
+packages/debugger                                               @Datadog/rum-browser @DataDog/debugger
+packages/debugger/README.md                                     @Datadog/rum-browser @DataDog/debugger @DataDog/documentation
+test/apps/instrumentation-overhead                              @Datadog/rum-browser @DataDog/debugger
+test/e2e/scenario/debugger.scenario.ts                          @Datadog/rum-browser @DataDog/debugger
+test/performance/scenarios/instrumentationOverhead.scenario.ts  @Datadog/rum-browser @DataDog/debugger

LICENSE-3rdparty.csv

@@ -38,6 +38,7 @@ dev,@vitejs/plugin-react,MIT,Copyright (c) 2019-present Evan You & Vite Contribu
 dev,@vitejs/plugin-vue,MIT,Copyright (c) 2019-present, Yuxi (Evan) You and Vite contributors
 dev,@module-federation/enhanced,MIT, Copyright (c) 2020 ScriptedAlchemy LLC (Zack Jackson) Zhou Shaw (zhouxiao)
 dev,@vue/test-utils,MIT,Copyright (c) 2021-present vuejs
+dev,acorn,MIT,Copyright (C) 2012-2022 by various contributors (see AUTHORS)
 dev,ajv,MIT,Copyright 2015-2017 Evgeny Poberezkin
 dev,babel-loader,MIT,Copyright (c) 2014-2019 Luís Couto <hello@luiscouto.pt>
 dev,browserstack-local,MIT,Copyright 2016 BrowserStack

eslint-local-rules/disallowSideEffects.js

@@ -29,6 +29,7 @@ const pathsWithSideEffect = new Set([
   `${packagesRoot}/logs/src/entries/main.ts`,
   `${packagesRoot}/rum/src/entries/main.ts`,
   `${packagesRoot}/rum-slim/src/entries/main.ts`,
+  `${packagesRoot}/debugger/src/entries/main.ts`,
 ])
 
 // Those packages are known to have no side effects when evaluated

packages/core/src/domain/configuration/configuration.ts

@@ -311,6 +311,8 @@ export interface ReplicaUserConfiguration {
   clientToken: string
 }
 
+export type SdkSource = 'browser' | 'flutter' | 'unity'
+
 export interface Configuration extends TransportConfiguration {
   // Built from init configuration
   beforeSend: GenericBeforeSendCallback | undefined
@@ -331,7 +333,6 @@ export interface Configuration extends TransportConfiguration {
 
   // internal
   sdkVersion: string | undefined
-  source: 'browser' | 'flutter' | 'unity'
   variant: string | undefined
 }
 

packages/core/src/domain/configuration/endpointBuilder.ts

@@ -8,18 +8,34 @@ import type { InitConfiguration } from './configuration'
 // replaced at build time
 declare const __BUILD_ENV__SDK_VERSION__: string
 
-export type TrackType = 'logs' | 'rum' | 'replay' | 'profile' | 'exposures' | 'flagevaluation'
+export type TrackType = 'logs' | 'rum' | 'replay' | 'profile' | 'exposures' | 'flagevaluation' | 'debugger'
 export type ApiType =
   | 'fetch'
   | 'beacon'
   // 'manual' reflects that the request have been sent manually, outside of the SDK (ex: via curl or
   // a Node.js script).
   | 'manual'
 
+/**
+ * Source values supported by the transport layer for the `ddsource` URL parameter.
+ *
+ * `'dd_debugger'` is internal to the Live Debugger SDK and is not part of
+ * `InitConfiguration.source`. It can only be supplied by passing it as the
+ * `sourceOverride` argument of `computeTransportConfiguration`.
+ */
+export type TransportSource = 'browser' | 'flutter' | 'unity' | 'dd_debugger'
+
+// Internal: the endpoint builder accepts a wider `source` than the public
+// `InitConfiguration.source` so that `computeTransportConfiguration` can pass
+// the validated/overridden transport source through to URL building.
+type EndpointBuilderInitConfiguration = Omit<InitConfiguration, 'source'> & {
+  source?: TransportSource
+}
+
 export type EndpointBuilder = ReturnType<typeof createEndpointBuilder>
 
 export function createEndpointBuilder(
-  initConfiguration: InitConfiguration,
+  initConfiguration: EndpointBuilderInitConfiguration,
   trackType: TrackType,
   extraParameters?: string[]
 ) {
@@ -40,7 +56,7 @@ export function createEndpointBuilder(
  * request, as only parameters are changing.
  */
 function createEndpointUrlWithParametersBuilder(
-  initConfiguration: InitConfiguration,
+  initConfiguration: EndpointBuilderInitConfiguration,
   trackType: TrackType
 ): (parameters: string) => string {
   const path = `/api/v2/${trackType}`
@@ -58,7 +74,7 @@ function createEndpointUrlWithParametersBuilder(
 
 export function buildEndpointHost(
   trackType: TrackType,
-  initConfiguration: InitConfiguration & { usePciIntake?: boolean }
+  initConfiguration: Omit<InitConfiguration, 'source'> & { usePciIntake?: boolean }
 ) {
   const { site = INTAKE_SITE_US1, internalAnalyticsSubdomain } = initConfiguration
 
@@ -84,7 +100,7 @@ export function buildEndpointHost(
  * request, as they change randomly.
  */
 function buildEndpointParameters(
-  { clientToken, internalAnalyticsSubdomain, source = 'browser' }: InitConfiguration,
+  { clientToken, internalAnalyticsSubdomain, source = 'browser' }: EndpointBuilderInitConfiguration,
   trackType: TrackType,
   api: ApiType,
   { retry, encoding }: Payload,

packages/core/src/domain/configuration/transportConfiguration.ts

@@ -1,7 +1,7 @@
 import type { Site } from '../intakeSites'
 import { INTAKE_SITE_US1, INTAKE_URL_PARAMETERS } from '../intakeSites'
-import type { InitConfiguration } from './configuration'
-import type { EndpointBuilder } from './endpointBuilder'
+import type { InitConfiguration, SdkSource } from './configuration'
+import type { EndpointBuilder, TransportSource } from './endpointBuilder'
 import { createEndpointBuilder } from './endpointBuilder'
 
 export interface TransportConfiguration {
@@ -11,23 +11,48 @@ export interface TransportConfiguration {
   profilingEndpointBuilder: EndpointBuilder
   exposuresEndpointBuilder: EndpointBuilder
   flagEvaluationEndpointBuilder: EndpointBuilder
+  debuggerEndpointBuilder: EndpointBuilder
   datacenter?: string | undefined
   replica?: ReplicaConfiguration
   site: Site
-  source: 'browser' | 'flutter' | 'unity'
+  source: SdkSource
 }
 
 export interface ReplicaConfiguration {
   logsEndpointBuilder: EndpointBuilder
   rumEndpointBuilder: EndpointBuilder
 }
 
-export function computeTransportConfiguration(initConfiguration: InitConfiguration): TransportConfiguration {
+// Internal: init configuration once the transport source has been resolved
+// (validated user value or `sourceOverride` from `computeTransportConfiguration`).
+type ResolvedSourceInitConfiguration = Omit<InitConfiguration, 'source'> & {
+  source: TransportSource
+}
+
+/**
+ * Compute the transport configuration (endpoint builders, replica, etc.) for an
+ * SDK init configuration.
+ *
+ * `sourceOverride` (if provided) is only used to build the `ddsource` URL
+ * parameter on outgoing requests; it does not appear on the returned
+ * `TransportConfiguration.source`, which is always the validated `SdkSource`
+ * derived from `initConfiguration.source`.
+ */
+export function computeTransportConfiguration(
+  initConfiguration: InitConfiguration,
+  sourceOverride?: TransportSource
+): TransportConfiguration {
   const site = initConfiguration.site || INTAKE_SITE_US1
   const source = validateSource(initConfiguration.source)
+  const transportSource: TransportSource = sourceOverride ?? source
 
-  const endpointBuilders = computeEndpointBuilders({ ...initConfiguration, site, source })
-  const replicaConfiguration = computeReplicaConfiguration({ ...initConfiguration, site, source })
+  const resolvedConfiguration: ResolvedSourceInitConfiguration = {
+    ...initConfiguration,
+    site,
+    source: transportSource,
+  }
+  const endpointBuilders = computeEndpointBuilders(resolvedConfiguration)
+  const replicaConfiguration = computeReplicaConfiguration(resolvedConfiguration)
 
   return {
     replica: replicaConfiguration,
@@ -37,30 +62,33 @@ export function computeTransportConfiguration(initConfiguration: InitConfigurati
   }
 }
 
-function validateSource(source: string | undefined) {
+function validateSource(source: string | undefined): SdkSource {
   if (source === 'flutter' || source === 'unity') {
     return source
   }
   return 'browser'
 }
 
-function computeEndpointBuilders(initConfiguration: InitConfiguration) {
+function computeEndpointBuilders(initConfiguration: ResolvedSourceInitConfiguration) {
   return {
     logsEndpointBuilder: createEndpointBuilder(initConfiguration, 'logs'),
     rumEndpointBuilder: createEndpointBuilder(initConfiguration, 'rum'),
     profilingEndpointBuilder: createEndpointBuilder(initConfiguration, 'profile'),
     sessionReplayEndpointBuilder: createEndpointBuilder(initConfiguration, 'replay'),
     exposuresEndpointBuilder: createEndpointBuilder(initConfiguration, 'exposures'),
     flagEvaluationEndpointBuilder: createEndpointBuilder(initConfiguration, 'flagevaluation'),
+    debuggerEndpointBuilder: createEndpointBuilder(initConfiguration, 'debugger'),
   }
 }
 
-function computeReplicaConfiguration(initConfiguration: InitConfiguration): ReplicaConfiguration | undefined {
+function computeReplicaConfiguration(
+  initConfiguration: ResolvedSourceInitConfiguration
+): ReplicaConfiguration | undefined {
   if (!initConfiguration.replica) {
     return
   }
 
-  const replicaConfiguration: InitConfiguration = {
+  const replicaConfiguration: ResolvedSourceInitConfiguration = {
     ...initConfiguration,
     site: INTAKE_SITE_US1,
     clientToken: initConfiguration.replica.clientToken,

packages/core/src/index.ts

@@ -7,6 +7,7 @@ export {
   isSampleRate,
   buildEndpointHost,
   isIntakeUrl,
+  computeTransportConfiguration,
 } from './domain/configuration'
 export * from './domain/intakeSites'
 export type { TrackingConsentState } from './domain/trackingConsent'
@@ -57,7 +58,15 @@ export {
   SESSION_NOT_TRACKED,
   SessionPersistence,
 } from './domain/session/sessionConstants'
-export type { BandwidthStats, HttpRequest, HttpRequestEvent, Payload, FlushEvent, FlushReason } from './transport'
+export type {
+  Batch,
+  BandwidthStats,
+  HttpRequest,
+  HttpRequestEvent,
+  Payload,
+  FlushEvent,
+  FlushReason,
+} from './transport'
 export {
   createHttpRequest,
   canUseEventBridge,

packages/core/src/transport/index.ts

@@ -2,6 +2,7 @@ export type { BandwidthStats, HttpRequest, HttpRequestEvent, Payload, RetryInfo
 export { createHttpRequest } from './httpRequest'
 export type { BrowserWindowWithEventBridge, DatadogEventBridge } from './eventBridge'
 export { canUseEventBridge, bridgeSupports, getEventBridge, BridgeCapability } from './eventBridge'
+export type { Batch } from './batch'
 export { createBatch } from './batch'
 export type { FlushController, FlushEvent, FlushReason } from './flushController'
 export { createFlushController, FLUSH_DURATION_LIMIT } from './flushController'