✨ Add tab.id to all RUM and Logs events

packages/core/src/domain/contexts/tabContext.spec.ts

@@ -0,0 +1,107 @@
+import type { Hooks } from '../../../test'
+import { createHooks, registerCleanupTask } from '../../../test'
+import { HookNames } from '../../tools/abstractHooks'
+import type { RelativeTime } from '../../tools/utils/timeUtils'
+import { TAB_ID_STORAGE_KEY, resetCachedTabId, startTabContext } from './tabContext'
+
+const UUID_PATTERN = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
+
+describe('tabContext', () => {
+  let hooks: Hooks
+
+  beforeEach(() => {
+    resetCachedTabId()
+    hooks = createHooks()
+    registerCleanupTask(() => {
+      sessionStorage.removeItem(TAB_ID_STORAGE_KEY)
+      resetCachedTabId()
+    })
+  })
+
+  it('should return a tab ID via the assemble hook', () => {
+    startTabContext(hooks)
+
+    const event = hooks.triggerHook(HookNames.Assemble, {
+      startTime: 0 as RelativeTime,
+    })
+
+    expect(event).toEqual(
+      jasmine.objectContaining({
+        tab: jasmine.objectContaining({
+          id: jasmine.stringMatching(UUID_PATTERN),
+        }),
+      })
+    )
+  })
+
+  it('should return a consistent tab ID across multiple hook triggers', () => {
+    startTabContext(hooks)
+
+    const event1 = hooks.triggerHook(HookNames.Assemble, {
+      startTime: 0 as RelativeTime,
+    })
+    const event2 = hooks.triggerHook(HookNames.Assemble, {
+      startTime: 0 as RelativeTime,
+    })
+
+    expect(event1.tab.id).toBe(event2.tab.id)
+  })
+
+  it('should persist the tab ID to sessionStorage', () => {
+    startTabContext(hooks)
+
+    const event = hooks.triggerHook(HookNames.Assemble, {
+      startTime: 0 as RelativeTime,
+    })
+
+    expect(sessionStorage.getItem(TAB_ID_STORAGE_KEY)).toBe(event.tab.id)
+  })
+
+  it('should reuse an existing tab ID from sessionStorage', () => {
+    sessionStorage.setItem(TAB_ID_STORAGE_KEY, 'existing-tab-id')
+    startTabContext(hooks)
+
+    const event = hooks.triggerHook(HookNames.Assemble, {
+      startTime: 0 as RelativeTime,
+    })
+
+    expect(event.tab.id).toBe('existing-tab-id')
+  })
+
+  it('should generate a tab ID when sessionStorage.getItem throws', () => {
+    spyOn(sessionStorage, 'getItem').and.throwError('SecurityError')
+    startTabContext(hooks)
+
+    const event = hooks.triggerHook(HookNames.Assemble, {
+      startTime: 0 as RelativeTime,
+    })
+
+    expect(event.tab.id).toMatch(UUID_PATTERN)
+  })
+
+  it('should generate a tab ID when sessionStorage.setItem throws', () => {
+    spyOn(sessionStorage, 'getItem').and.returnValue(null)
+    spyOn(sessionStorage, 'setItem').and.throwError('QuotaExceededError')
+    startTabContext(hooks)
+
+    const event = hooks.triggerHook(HookNames.Assemble, {
+      startTime: 0 as RelativeTime,
+    })
+
+    expect(event.tab.id).toMatch(UUID_PATTERN)
+  })
+
+  it('should return the same tab ID across multiple startTabContext calls when sessionStorage is unavailable', () => {
+    spyOn(sessionStorage, 'getItem').and.throwError('SecurityError')
+
+    const hooks1 = createHooks()
+    startTabContext(hooks1)
+    const hooks2 = createHooks()
+    startTabContext(hooks2)
+
+    const event1 = hooks1.triggerHook(HookNames.Assemble, { startTime: 0 as RelativeTime })
+    const event2 = hooks2.triggerHook(HookNames.Assemble, { startTime: 0 as RelativeTime })
+
+    expect(event1.tab.id).toBe(event2.tab.id)
+  })
+})

packages/core/src/domain/contexts/tabContext.ts

@@ -0,0 +1,44 @@
+import { HookNames } from '../../tools/abstractHooks'
+import type { AbstractHooks } from '../../tools/abstractHooks'
+import { generateUUID } from '../../tools/utils/stringUtils'
+
+export const TAB_ID_STORAGE_KEY = '_dd_tab_id'
+
+let cachedTabId: string | undefined
+
+// Exported for test cleanup only — allows specs to reset the in-memory cache between tests.
+export function resetCachedTabId(): void {
+  cachedTabId = undefined
+}
+
+export function startTabContext(hooks: AbstractHooks) {
+  const tabId = retrieveOrCreateTabId()
+
+  hooks.register(HookNames.Assemble, () => ({
+    tab: {
+      id: tabId,
+    },
+  }))
+}
+
+function retrieveOrCreateTabId(): string {
+  if (!cachedTabId) {
+    cachedTabId = getOrCreateIdInSessionStorage() ?? generateUUID()
+  }
+  return cachedTabId
+}
+
+function getOrCreateIdInSessionStorage(): string | undefined {
+  try {
+    const existingId = sessionStorage.getItem(TAB_ID_STORAGE_KEY)
+    if (existingId) {
+      return existingId
+    }
+    const newId = generateUUID()
+    sessionStorage.setItem(TAB_ID_STORAGE_KEY, newId)
+    return newId
+  } catch {
+    // sessionStorage unavailable (e.g. Web Worker, sandboxed iframe, quota exceeded)
+    return undefined
+  }
+}

packages/core/src/index.ts

@@ -123,6 +123,7 @@ export { createContextManager } from './domain/context/contextManager'
 export { defineContextMethod, bufferContextCalls } from './domain/context/defineContextMethod'
 export { storeContextManager, removeStorageListeners } from './domain/context/storeContextManager'
 export { startAccountContext, buildAccountContextManager } from './domain/contexts/accountContext'
+export { startTabContext } from './domain/contexts/tabContext'
 export { startGlobalContext, buildGlobalContextManager } from './domain/contexts/globalContext'
 export { startUserContext, buildUserContextManager } from './domain/contexts/userContext'
 export type { User } from './domain/contexts/userContext'

packages/logs/src/boot/startLogs.spec.ts

@@ -128,6 +128,9 @@ describe('logs', () => {
         usr: {
           anonymous_id: jasmine.any(String),
         },
+        tab: {
+          id: jasmine.any(String),
+        },
       })
     })
 

packages/logs/src/boot/startLogs.ts

@@ -7,6 +7,7 @@ import {
   startAccountContext,
   startGlobalContext,
   startUserContext,
+  startTabContext,
 } from '@datadog/browser-core'
 import { startLogsSessionManager, startLogsSessionManagerStub } from '../domain/logsSessionManager'
 import type { LogsConfiguration } from '../domain/configuration'
@@ -63,6 +64,7 @@ export function startLogs(
   const userContext = startUserContext(hooks, configuration, session, LOGS_STORAGE_KEY)
   const globalContext = startGlobalContext(hooks, configuration, LOGS_STORAGE_KEY, false)
   startRUMInternalContext(hooks)
+  startTabContext(hooks)
 
   startNetworkErrorCollection(configuration, lifeCycle)
   startRuntimeErrorCollection(configuration, lifeCycle, bufferedDataObservable)

packages/rum-core/src/boot/startRum.ts

@@ -16,6 +16,7 @@ import {
   startAccountContext,
   startGlobalContext,
   startUserContext,
+  startTabContext,
 } from '@datadog/browser-core'
 import { createDOMMutationObservable } from '../browser/domMutationObservable'
 import { createWindowOpenObservable } from '../browser/windowOpenObservable'
@@ -181,6 +182,7 @@ export function startRumEventCollection(
   const featureFlagContexts = startFeatureFlagContexts(lifeCycle, hooks, configuration)
   startSessionContext(hooks, session, recorderApi, viewHistory)
   startConnectivityContext(hooks)
+  startTabContext(hooks)
   const globalContext = startGlobalContext(hooks, configuration, 'rum', true)
   const userContext = startUserContext(hooks, configuration, session, 'rum')
   const accountContext = startAccountContext(hooks, configuration, 'rum')

packages/rum-core/src/domain/assembly.spec.ts

@@ -6,6 +6,7 @@ import {
   display,
   relativeToClocks,
   startGlobalContext,
+  startTabContext,
 } from '@datadog/browser-core'
 import type { Clock } from '@datadog/browser-core/test'
 import { registerCleanupTask, mockClock } from '@datadog/browser-core/test'
@@ -510,6 +511,18 @@ describe('rum assembly', () => {
       })
       expect(serverRumEvents[0].context).toEqual({ foo: 'customer context' })
     })
+
+    it('should include tab.id from tabContext', () => {
+      const { lifeCycle, hooks, serverRumEvents } = setupAssemblyTestWithDefaults()
+
+      startTabContext(hooks)
+
+      notifyRawRumEvent(lifeCycle, {
+        rawRumEvent: createRawRumEvent(RumEventType.VIEW),
+      })
+
+      expect((serverRumEvents[0] as any).tab.id).toEqual(jasmine.any(String))
+    })
   })
 
   describe('event generation condition', () => {