Default debugger init version from build metadata

Use build-plugin injected Live Debugger metadata as the default runtime
`init().version`, and warn when an explicit init version disagrees.
Document the fallback behavior and cover the new version resolution path
in unit tests.

Author: watson

packages/debugger/README.md

@@ -21,6 +21,8 @@ datadogDebugger.init({
 })
 ```
 
+When you also use the Datadog Live Debugger build plugin, `init().version` defaults to the build-time `liveDebugger.version` metadata injected into the bundle. If you pass both values explicitly and they differ, the SDK keeps the `init()` value and logs a warning.
+
 If [Datadog RUM][3] is also initialized on the page, debugger snapshots automatically include RUM context (session, view, user action) without any additional configuration.
 
 ## Troubleshooting

packages/debugger/src/entries/main.spec.ts

@@ -1,11 +1,100 @@
+import { display } from '@datadog/browser-core'
+import { registerCleanupTask, replaceMockableWithSpy } from '@datadog/browser-core/test'
+import { initDebuggerTransport } from '../domain/api'
+import { startDeliveryApiPolling } from '../domain/deliveryApi'
+import { startDebuggerBatch } from '../transport/startDebuggerBatch'
+import type { BrowserWindow } from './main'
 import { datadogDebugger } from './main'
 
 describe('datadogDebugger', () => {
+  const browserWindow: BrowserWindow = window
+
+  beforeEach(() => {
+    delete browserWindow.__DD_LIVE_DEBUGGER_BUILD__
+    delete browserWindow.$dd_entry
+    delete browserWindow.$dd_return
+    delete browserWindow.$dd_throw
+    delete browserWindow.$dd_probes
+
+    registerCleanupTask(() => {
+      delete browserWindow.__DD_LIVE_DEBUGGER_BUILD__
+      delete browserWindow.$dd_entry
+      delete browserWindow.$dd_return
+      delete browserWindow.$dd_throw
+      delete browserWindow.$dd_probes
+    })
+  })
+
   it('should only expose init, version, and onReady', () => {
     expect(datadogDebugger).toEqual({
       init: jasmine.any(Function),
       version: jasmine.any(String),
       onReady: jasmine.any(Function),
     })
   })
+
+  it('should default the init version from build-plugin metadata', async () => {
+    browserWindow.__DD_LIVE_DEBUGGER_BUILD__ = { version: 'build-version' }
+    replaceMockableWithSpy(startDebuggerBatch).and.callFake(() => ({
+      flushController: undefined as any,
+      add: () => undefined,
+      flush: () => undefined,
+      stop: () => undefined,
+      upsert: () => undefined,
+    }))
+    const initTransportSpy = replaceMockableWithSpy(initDebuggerTransport)
+    const startDeliveryApiPollingSpy = replaceMockableWithSpy(startDeliveryApiPolling)
+
+    datadogDebugger.init({
+      applicationId: 'app-id',
+      clientToken: 'client-token',
+      service: 'service-name',
+      env: 'staging',
+    })
+
+    await flushPromises()
+
+    expect(initTransportSpy).toHaveBeenCalledWith(
+      jasmine.objectContaining({ version: 'build-version' }),
+      jasmine.anything()
+    )
+    expect(startDeliveryApiPollingSpy).toHaveBeenCalledWith(jasmine.objectContaining({ version: 'build-version' }))
+    expect(browserWindow.$dd_entry).toBeDefined()
+    expect(browserWindow.$dd_return).toBeDefined()
+    expect(browserWindow.$dd_throw).toBeDefined()
+    expect(browserWindow.$dd_probes).toBeDefined()
+  })
+
+  it('should warn when the explicit init version mismatches build-plugin metadata', async () => {
+    browserWindow.__DD_LIVE_DEBUGGER_BUILD__ = { version: 'build-version' }
+    replaceMockableWithSpy(startDebuggerBatch).and.callFake(() => ({
+      flushController: undefined as any,
+      add: () => undefined,
+      flush: () => undefined,
+      stop: () => undefined,
+      upsert: () => undefined,
+    }))
+    replaceMockableWithSpy(initDebuggerTransport)
+    const startDeliveryApiPollingSpy = replaceMockableWithSpy(startDeliveryApiPolling)
+    const warnSpy = spyOn(display, 'warn')
+
+    datadogDebugger.init({
+      applicationId: 'app-id',
+      clientToken: 'client-token',
+      service: 'service-name',
+      env: 'staging',
+      version: 'runtime-version',
+    })
+
+    await flushPromises()
+
+    expect(warnSpy).toHaveBeenCalledWith(jasmine.stringMatching(/does not match the build-plugin version/))
+    expect(startDeliveryApiPollingSpy).toHaveBeenCalledWith(jasmine.objectContaining({ version: 'runtime-version' }))
+  })
 })
+
+async function flushPromises() {
+  for (let i = 0; i < 10; i++) {
+    await Promise.resolve()
+  }
+}

packages/debugger/src/entries/main.ts

@@ -6,13 +6,17 @@
  * @see [Live Debugger Documentation](https://docs.datadoghq.com/tracing/live_debugger/)
  */
 
-import { defineGlobal, getGlobalObject, makePublicApi } from '@datadog/browser-core'
+import { defineGlobal, display, getGlobalObject, makePublicApi, mockable } from '@datadog/browser-core'
 import type { PublicApi, Site } from '@datadog/browser-core'
-import { onEntry, onReturn, onThrow, initDebuggerTransport } from '../domain/api'
+import { initDebuggerTransport, onEntry, onReturn, onThrow } from '../domain/api'
 import { startDeliveryApiPolling } from '../domain/deliveryApi'
 import { getProbes } from '../domain/probes'
 import { startDebuggerBatch } from '../transport/startDebuggerBatch'
 
+export interface DebuggerBuildMetadata {
+  version?: string
+}
+
 /**
  * Configuration options for initializing the Live Debugger SDK
  */
@@ -94,29 +98,58 @@ export interface DebuggerPublicApi extends PublicApi {
   init: (initConfiguration: DebuggerInitConfiguration) => void
 }
 
+export interface BrowserWindow extends Window {
+  DD_DEBUGGER?: DebuggerPublicApi
+  __DD_LIVE_DEBUGGER_BUILD__?: DebuggerBuildMetadata
+  $dd_entry?: typeof onEntry
+  $dd_return?: typeof onReturn
+  $dd_throw?: typeof onThrow
+  $dd_probes?: typeof getProbes
+}
+
+function resolveDebuggerVersion(initConfiguration: DebuggerInitConfiguration): string | undefined {
+  const buildVersion = getGlobalObject<BrowserWindow>().__DD_LIVE_DEBUGGER_BUILD__?.version
+
+  if (
+    initConfiguration.version !== undefined &&
+    buildVersion !== undefined &&
+    initConfiguration.version !== buildVersion
+  ) {
+    display.warn(
+      `Debugger: init version "${initConfiguration.version}" does not match the build-plugin version "${buildVersion}". Using the init version.`
+    )
+  }
+
+  return initConfiguration.version ?? buildVersion
+}
+
 /**
  * Create the public API for the Live Debugger
  */
 function makeDebuggerPublicApi(): DebuggerPublicApi {
   return makePublicApi<DebuggerPublicApi>({
     init: (initConfiguration: DebuggerInitConfiguration) => {
+      const resolvedConfiguration = {
+        ...initConfiguration,
+        version: resolveDebuggerVersion(initConfiguration),
+      }
+
       // Initialize debugger's own transport
-      const batch = startDebuggerBatch(initConfiguration)
-      initDebuggerTransport(initConfiguration, batch)
+      const batch = mockable(startDebuggerBatch)(resolvedConfiguration)
+      mockable(initDebuggerTransport)(resolvedConfiguration, batch)
 
       // Expose internal hooks on globalThis for instrumented code
-      if (typeof globalThis !== 'undefined') {
-        ;(globalThis as any).$dd_entry = onEntry
-        ;(globalThis as any).$dd_return = onReturn
-        ;(globalThis as any).$dd_throw = onThrow
-        ;(globalThis as any).$dd_probes = getProbes
-      }
+      const debuggerGlobal = getGlobalObject<BrowserWindow>()
+      debuggerGlobal.$dd_entry = onEntry
+      debuggerGlobal.$dd_return = onReturn
+      debuggerGlobal.$dd_throw = onThrow
+      debuggerGlobal.$dd_probes = getProbes
 
-      startDeliveryApiPolling({
-        applicationId: initConfiguration.applicationId,
-        env: initConfiguration.env,
-        version: initConfiguration.version,
-        pollInterval: initConfiguration.pollInterval,
+      mockable(startDeliveryApiPolling)({
+        applicationId: resolvedConfiguration.applicationId,
+        env: resolvedConfiguration.env,
+        version: resolvedConfiguration.version,
+        pollInterval: resolvedConfiguration.pollInterval,
       })
     },
   })
@@ -131,8 +164,4 @@ function makeDebuggerPublicApi(): DebuggerPublicApi {
  */
 export const datadogDebugger = makeDebuggerPublicApi()
 
-export interface BrowserWindow extends Window {
-  DD_DEBUGGER?: DebuggerPublicApi
-}
-
 defineGlobal(getGlobalObject<BrowserWindow>(), 'DD_DEBUGGER', datadogDebugger)