@kubesense/kubesense-browser-rum 1.7.0 → 2.0.0-beta.1

package/src/domain/profiling/{profiler.ts → kubesenseProfiler.ts}

@@ -1,76 +1,95 @@
-import type { Encoder } from '@kubesense/kubesense-browser-core'
+import { globalObject } from '@kubesense/kubesense-js-core/util'
+import type { Profiler } from '@kubesense/kubesense-js-core/util'
+import { elapsed, clocksOrigin, clocksNow } from '@kubesense/kubesense-js-core/time'
+import type { SessionManager, DeflateEncoderStreamId, Encoder } from '@kubesense/kubesense-browser-core'
 import {
   addEventListener,
+  canUseEventBridge,
   clearTimeout,
   setTimeout,
   DOM_EVENT,
-  monitorError,
   display,
-  getGlobalObject,
-  clocksOrigin,
-  clocksNow,
-  elapsed,
-  DeflateEncoderStreamId,
+  mockable,
+  isSampled,
+  correctedChildSampleRate,
 } from '@kubesense/kubesense-browser-core'
+import { monitorError } from '@kubesense/kubesense-js-core/monitor'
 
+import type { LifeCycle, RumConfiguration, ViewHistory } from '@kubesense/kubesense-browser-rum-core'
+import { LifeCycleEventType } from '@kubesense/kubesense-browser-rum-core'
+import type { BrowserProfilerTrace, RumViewEntry } from '../../types'
 import type {
-  LifeCycle,
-  LongTaskContexts,
-  RumConfiguration,
-  RumSessionManager,
-  TransportPayload,
-  ViewHistory,
-} from '@kubesense/kubesense-browser-rum-core'
-import { createFormDataTransport, LifeCycleEventType } from '@kubesense/kubesense-browser-rum-core'
-import type {
-  RumProfilerTrace,
   RumProfilerInstance,
-  Profiler,
+  RumProfilerRunningInstance,
   RUMProfiler,
   RUMProfilerConfiguration,
   RumProfilerStoppedInstance,
-  RumViewEntry,
+  ProfilingPayload,
 } from './types'
-import { getNumberOfSamples } from './utils/getNumberOfSamples'
 import type { ProfilingContextManager } from './profilingContext'
+import { createBridgeEmitter } from './transport/profilingBridge'
+import { createFormDataEmitter } from './transport/formDataEmitter'
 import { getCustomOrDefaultViewName } from './utils/getCustomOrDefaultViewName'
-import { assembleProfilingPayload } from './transport/assembly'
+import { buildProfileEvent } from './transport/buildProfileEvent'
+import { createLongTaskHistory } from './longTaskHistory'
+import { createActionHistory } from './actionHistory'
+import { createVitalHistory } from './vitalHistory'
+import { checkProfilingQuota } from './quotaCheck'
+import type { QuotaReason } from './quotaCheck'
+import { buildProfilerDebugIds } from './profilerDebugIds'
 
 export const DEFAULT_RUM_PROFILER_CONFIGURATION: RUMProfilerConfiguration = {
   sampleIntervalMs: 10, // Sample stack trace every 10ms
   collectIntervalMs: 60000, // Collect data every minute
   minProfileDurationMs: 5000, // Require at least 5 seconds of profile data to reduce noise and cost
-  minNumberOfSamples: 50, // Require at least 50 samples (~500 ms) to report a profile to reduce noise and cost
 }
 
 export function createRumProfiler(
   configuration: RumConfiguration,
   lifeCycle: LifeCycle,
-  session: RumSessionManager,
+  session: SessionManager,
   profilingContextManager: ProfilingContextManager,
-  longTaskContexts: LongTaskContexts,
   createEncoder: (streamId: DeflateEncoderStreamId) => Encoder,
   viewHistory: ViewHistory,
   profilerConfiguration: RUMProfilerConfiguration = DEFAULT_RUM_PROFILER_CONFIGURATION
 ): RUMProfiler {
-  const transport = createFormDataTransport(configuration, lifeCycle, createEncoder, DeflateEncoderStreamId.PROFILING)
+  const emitPayload = canUseEventBridge()
+    ? mockable(createBridgeEmitter)()
+    : mockable(createFormDataEmitter)(configuration, lifeCycle, createEncoder)
 
   let lastViewEntry: RumViewEntry | undefined
 
   // Global clean-up tasks for listeners that are not specific to a profiler instance (eg. visibility change, before unload)
   const globalCleanupTasks: Array<() => void> = []
+  const longTaskHistory = mockable(createLongTaskHistory)(lifeCycle)
+  const actionHistory = mockable(createActionHistory)(lifeCycle)
+  const vitalHistory = mockable(createVitalHistory)(lifeCycle)
 
   let instance: RumProfilerInstance = { state: 'stopped', stateReason: 'initializing' }
+  let quotaCheckGeneration = 0
 
   // Stops the profiler when session expires
   lifeCycle.subscribe(LifeCycleEventType.SESSION_EXPIRED, () => {
-    stopProfiling('session-expired').catch(monitorError)
+    stopProfiling('session-expired')
   })
 
   // Start the profiler again when session is renewed
   lifeCycle.subscribe(LifeCycleEventType.SESSION_RENEWED, () => {
-    if (instance.state === 'stopped' && instance.stateReason === 'session-expired') {
-      start() // Only restart the profiler if it was stopped due to session expiration. Avoid restarting the profiler if it was stopped manually by the user.
+    if (
+      instance.state === 'stopped' &&
+      (instance.stateReason === 'session-expired' || instance.stateReason === 'quota_ko')
+    ) {
+      const newSession = session.findTrackedSession()
+      if (
+        !newSession ||
+        !isSampled(
+          newSession.id,
+          correctedChildSampleRate(configuration.sessionSampleRate, configuration.profilingSampleRate)
+        )
+      ) {
+        return
+      }
+      start()
     }
   })
 
@@ -94,28 +113,57 @@ export function createRumProfiler(
 
     // Add global clean-up tasks for listeners that are not specific to a profiler instance (eg. visibility change, before unload)
     globalCleanupTasks.push(
-      addEventListener(configuration, window, DOM_EVENT.VISIBILITY_CHANGE, handleVisibilityChange).stop,
-      addEventListener(configuration, window, DOM_EVENT.BEFORE_UNLOAD, handleBeforeUnload).stop
+      addEventListener(window, DOM_EVENT.VISIBILITY_CHANGE, handleVisibilityChange).stop,
+      addEventListener(window, DOM_EVENT.BEFORE_UNLOAD, handleBeforeUnload).stop
     )
 
     // Start profiler instance
     startNextProfilerInstance()
+    triggerQuotaCheck()
+  }
+
+  function triggerQuotaCheck() {
+    if (canUseEventBridge()) {
+      // Quota check only in non-bridge mode.
+      return
+    }
+    // Optimistic: profiler already recording, only gates sending.
+    // Generation counter invalidates results from a prior session (incremented on each start() call).
+    // State guard handles within-session cancellation (user stop, session expiry, etc.).
+    const checkGeneration = ++quotaCheckGeneration
+    const sessionId = session.findTrackedSession()?.id
+    if (sessionId) {
+      mockable(checkProfilingQuota)(configuration, sessionId)
+        .then((result) => {
+          if (checkGeneration !== quotaCheckGeneration) {
+            return
+          }
+          if (instance.state !== 'running' && instance.state !== 'paused') {
+            return
+          }
+          if (result.decision === 'quota_ko') {
+            stopProfiling('quota_ko', result.reason)
+          }
+        })
+        .catch(monitorError)
+    }
   }
 
   // Public API to manually stop the profiler.
-  async function stop() {
-    await stopProfiling('stopped-by-user')
+  function stop() {
+    stopProfiling('stopped-by-user')
   }
 
-  async function stopProfiling(reason: RumProfilerStoppedInstance['stateReason']) {
-    // Stop current profiler instance
-    await stopProfilerInstance(reason)
+  function stopProfiling(reason: RumProfilerStoppedInstance['stateReason'], quotaReason?: QuotaReason) {
+    // Stop current profiler instance (data collection happens async in background)
+    stopProfilerInstance(reason)
 
-    // Cleanup global listeners
+    // Cleanup global listeners and reset the array to prevent accumulation across start/stop cycles
     globalCleanupTasks.forEach((task) => task())
+    globalCleanupTasks.length = 0
 
     // Update Profiling status once the Profiler has been stopped.
-    profilingContextManager.set({ status: 'stopped', error_reason: undefined })
+    profilingContextManager.set({ status: 'stopped', error_reason: undefined, quota_reason: quotaReason })
   }
 
   /**
@@ -156,22 +204,24 @@ export function createRumProfiler(
 
   function startNextProfilerInstance(): void {
     // These APIs might be unavailable in some browsers
-    const globalThisProfiler: Profiler | undefined = getGlobalObject<any>().Profiler
+    const profilerConstructor = globalObject.Profiler
 
-    if (!globalThisProfiler) {
+    if (!profilerConstructor) {
       profilingContextManager.set({ status: 'error', error_reason: 'not-supported-by-browser' })
       throw new Error('RUM Profiler is not supported in this browser.')
     }
 
-    // Don't wait for data collection to start next instance
-    collectProfilerInstance(instance).catch(monitorError)
+    // Collect data from previous running instance (fire-and-forget)
+    if (instance.state === 'running') {
+      collectProfilerInstance(instance)
+    }
 
     const { cleanupTasks } = addEventListeners(instance)
 
     let profiler: Profiler
     try {
       // We have to create new Profiler each time we start a new instance
-      profiler = new globalThisProfiler({
+      profiler = new profilerConstructor({
         sampleInterval: profilerConfiguration.sampleIntervalMs,
         // Keep buffer size at 1.5 times of minimum required to collect data for a profiling instance
         maxBufferSize: Math.round(
@@ -204,81 +254,118 @@ export function createRumProfiler(
       views: [],
       cleanupTasks,
       longTasks: [],
+      sessionId: session.findTrackedSession()?.id,
     }
 
     // Add last view entry
     collectViewEntry(lastViewEntry)
 
     // Add event handler case we overflow the buffer
+    // eslint-disable-next-line local-rules/disallow-zone-js-patched-values -- FIXME use the `addEventListener` helper
     profiler.addEventListener('samplebufferfull', handleSampleBufferFull)
   }
 
-  async function collectProfilerInstance(lastInstance: RumProfilerInstance) {
-    if (lastInstance.state !== 'running') {
-      return
-    }
-
+  function collectProfilerInstance(runningInstance: RumProfilerRunningInstance) {
     // Cleanup instance
-    clearTimeout(lastInstance.timeoutId)
-    lastInstance.profiler.removeEventListener('samplebufferfull', handleSampleBufferFull)
+    clearTimeout(runningInstance.timeoutId)
+    // eslint-disable-next-line local-rules/disallow-zone-js-patched-values -- FIXME use the `addEventListener` helper
+    runningInstance.profiler.removeEventListener('samplebufferfull', handleSampleBufferFull)
 
     // Store instance data snapshot in local variables to use in async callback
-    const { startClocks, views } = lastInstance
+    const { startClocks, views, sessionId } = runningInstance
 
     // Stop current profiler to get trace
-    await lastInstance.profiler
+    runningInstance.profiler
       .stop()
       .then((trace) => {
         const endClocks = clocksNow()
-        const longTasks = longTaskContexts.findLongTasks(startClocks.relative)
-        const isBelowDurationThreshold =
-          elapsed(startClocks.timeStamp, endClocks.timeStamp) < profilerConfiguration.minProfileDurationMs
-        const isBelowSampleThreshold = getNumberOfSamples(trace.samples) < profilerConfiguration.minNumberOfSamples
-
-        if (longTasks.length === 0 && (isBelowDurationThreshold || isBelowSampleThreshold)) {
+        const duration = elapsed(startClocks.relative, endClocks.relative)
+        const longTasks = longTaskHistory.findAll(startClocks.relative, duration)
+        const actions = actionHistory.findAll(startClocks.relative, duration)
+        const vitals = vitalHistory.findAll(startClocks.relative, duration).map((vital) => ({
+          id: vital.id,
+          label: vital.label,
+          startClocks: vital.startClocks,
+          duration: vital.duration,
+        }))
+        const isBelowDurationThreshold = duration < profilerConfiguration.minProfileDurationMs
+
+        if (longTasks.length === 0 && isBelowDurationThreshold) {
           // Skip very short profiles to reduce noise and cost, but keep them if they contain long tasks.
           return
         }
 
         handleProfilerTrace(
-          // Enrich trace with time and instance data
-          Object.assign(trace, {
+          // Enrich trace with time and instance data — create new object to avoid mutating the raw trace
+          Object.assign({} as BrowserProfilerTrace, trace, {
             startClocks,
             endClocks,
             clocksOrigin: clocksOrigin(),
             longTasks,
+            actions,
+            vitals,
             views,
             sampleInterval: profilerConfiguration.sampleIntervalMs,
-          })
+            debugIds: buildProfilerDebugIds(trace.resources),
+          }),
+          sessionId
         )
       })
       .catch(monitorError)
   }
 
-  async function stopProfilerInstance(stateReason: RumProfilerStoppedInstance['stateReason']) {
+  function stopProfilerInstance(stateReason: RumProfilerStoppedInstance['stateReason']) {
     if (instance.state !== 'running') {
+      if (
+        // If paused, profiler data was already collected during pause, just update state
+        instance.state === 'paused' ||
+        // Update stateReason when already stopped and the user explicitly stops the profiler,
+        // so that SESSION_RENEWED does not override the user's intent.
+        (instance.state === 'stopped' && stateReason === 'stopped-by-user')
+      ) {
+        instance = { state: 'stopped', stateReason }
+      }
+
       return
     }
-    await onPauseOrStopProfilerInstance()
+
+    // Capture the running instance before changing state
+    const runningInstance = instance
+
+    // Update state synchronously so SESSION_RENEWED check works immediately
     instance = { state: 'stopped', stateReason }
-  }
 
-  async function pauseProfilerInstance() {
-    if (instance.state !== 'running') {
-      return
+    // Cleanup instance-specific tasks (e.g., view listener)
+    runningInstance.cleanupTasks.forEach((cleanupTask) => cleanupTask())
+
+    if (stateReason === 'quota_ko') {
+      // Discard data — quota denied means we should not send anything
+      clearTimeout(runningInstance.timeoutId)
+      // eslint-disable-next-line local-rules/disallow-zone-js-patched-values -- FIXME use the `addEventListener` helper
+      runningInstance.profiler.removeEventListener('samplebufferfull', handleSampleBufferFull)
+      void runningInstance.profiler.stop().catch(monitorError)
+    } else {
+      // Collect and send profile data in background - doesn't block state transitions
+      collectProfilerInstance(runningInstance)
     }
-    await onPauseOrStopProfilerInstance()
-    instance = { state: 'paused' }
   }
 
-  async function onPauseOrStopProfilerInstance() {
+  function pauseProfilerInstance() {
     if (instance.state !== 'running') {
       return
     }
-    // Cleanup tasks
-    instance.cleanupTasks.forEach((cleanupTask) => cleanupTask())
 
-    await collectProfilerInstance(instance)
+    // Capture the running instance before changing state
+    const runningInstance = instance
+
+    // Update state synchronously
+    instance = { state: 'paused' }
+
+    // Cleanup instance-specific tasks
+    runningInstance.cleanupTasks.forEach((cleanupTask) => cleanupTask())
+
+    // Collect and send profile data in background
+    collectProfilerInstance(runningInstance)
   }
 
   function collectViewEntry(viewEntry: RumViewEntry | undefined): void {
@@ -290,12 +377,12 @@ export function createRumProfiler(
     instance.views.push(viewEntry)
   }
 
-  function handleProfilerTrace(trace: RumProfilerTrace): void {
-    // Find current session to assign it to the Profile.
-    const sessionId = session.findTrackedSession()?.id
-    const payload = assembleProfilingPayload(trace, configuration, sessionId)
-
-    void transport.send(payload as unknown as TransportPayload)
+  function handleProfilerTrace(trace: BrowserProfilerTrace, sessionId: string | undefined): void {
+    const payload: ProfilingPayload = {
+      profile: buildProfileEvent(trace, configuration, sessionId),
+      trace,
+    }
+    emitPayload(payload)
   }
 
   function handleSampleBufferFull(): void {
@@ -308,7 +395,7 @@ export function createRumProfiler(
       // paused by visibility change and stopped by user.
       // If profiler is paused by the visibility change, we should resume when
       // tab becomes visible again. That's not the case when user stops the profiler.
-      pauseProfilerInstance().catch(monitorError)
+      pauseProfilerInstance()
     } else if (document.visibilityState === 'visible' && instance.state === 'paused') {
       // Resume when tab becomes visible again
       startNextProfilerInstance()

package/src/domain/profiling/longTaskHistory.ts

@@ -0,0 +1,45 @@
+import type { ClocksState, Duration } from '@kubesense/kubesense-js-core/time'
+import { addDuration } from '@kubesense/kubesense-js-core/time'
+import { createValueHistory, SESSION_TIME_OUT_DELAY } from '@kubesense/kubesense-browser-core'
+import type { LifeCycle } from '@kubesense/kubesense-browser-rum-core'
+import {
+  RumPerformanceEntryType,
+  LifeCycleEventType,
+  RumLongTaskEntryType,
+} from '@kubesense/kubesense-browser-rum-core'
+
+export const LONG_TASK_ID_HISTORY_EXPIRE_DELAY = SESSION_TIME_OUT_DELAY
+
+export interface LongTaskContext {
+  id: string
+  startClocks: ClocksState
+  duration: Duration
+  entryType: RumPerformanceEntryType.LONG_ANIMATION_FRAME | RumPerformanceEntryType.LONG_TASK
+}
+
+export function createLongTaskHistory(lifeCycle: LifeCycle) {
+  const history = createValueHistory<LongTaskContext>({
+    expireDelay: LONG_TASK_ID_HISTORY_EXPIRE_DELAY,
+  })
+
+  lifeCycle.subscribe(LifeCycleEventType.RAW_RUM_EVENT_COLLECTED, ({ rawRumEvent, startClocks, duration }) => {
+    if (rawRumEvent.type === 'long_task') {
+      history
+        .add(
+          {
+            id: rawRumEvent.long_task.id,
+            startClocks,
+            duration: duration!,
+            entryType:
+              rawRumEvent.long_task.entry_type === RumLongTaskEntryType.LONG_TASK
+                ? RumPerformanceEntryType.LONG_TASK
+                : RumPerformanceEntryType.LONG_ANIMATION_FRAME,
+          },
+          startClocks.relative
+        )
+        .close(addDuration(startClocks.relative, duration!))
+    }
+  })
+
+  return history
+}

package/src/domain/profiling/profilerDebugIds.ts

@@ -0,0 +1,17 @@
+import { buildDebugIdByUrl } from '@kubesense/kubesense-browser-core'
+import type { ResourceDebugId } from '../../types'
+
+export function buildProfilerDebugIds(resources: string[]): ResourceDebugId[] | undefined {
+  const debugIdByUrl = new Map(buildDebugIdByUrl(resources)?.map((entry) => [entry.url, entry.id]))
+
+  const debugIds: ResourceDebugId[] = []
+
+  resources.forEach((url, resourceId) => {
+    const debugId = debugIdByUrl.get(url)
+    if (debugId !== undefined) {
+      debugIds.push({ resourceId, debugId })
+    }
+  })
+
+  return debugIds.length ? debugIds : undefined
+}

package/src/domain/profiling/profilingContext.ts

@@ -1,4 +1,4 @@
-import { HookNames, SKIPPED } from '@kubesense/kubesense-browser-core'
+import { SKIPPED } from '@kubesense/kubesense-js-core/assembly'
 import type { Hooks, ProfilingInternalContextSchema } from '@kubesense/kubesense-browser-rum-core'
 import { RumEventType } from '@kubesense/kubesense-browser-rum-core'
 
@@ -12,8 +12,13 @@ export function startProfilingContext(hooks: Hooks): ProfilingContextManager {
     status: 'starting',
   }
 
-  hooks.register(HookNames.Assemble, ({ eventType }) => {
-    if (eventType !== RumEventType.VIEW && eventType !== RumEventType.LONG_TASK) {
+  hooks.assembleEventDefaults.register(({ eventType }) => {
+    if (
+      eventType !== RumEventType.VIEW &&
+      eventType !== RumEventType.LONG_TASK &&
+      eventType !== RumEventType.ACTION &&
+      eventType !== RumEventType.VITAL
+    ) {
       return SKIPPED
     }
 

package/src/domain/profiling/profilingSupported.ts

@@ -1,10 +1,5 @@
-import { getGlobalObject } from '@kubesense/kubesense-browser-core'
-import type { Profiler } from './types'
-
+import { globalObject } from '@kubesense/kubesense-js-core/util'
 export function isProfilingSupported(): boolean {
-  const globalThis = getGlobalObject()
-
   // This API might be unavailable in some browsers
-  const globalThisProfiler: Profiler | undefined = (globalThis as any).Profiler
-  return globalThisProfiler !== undefined
+  return globalObject.Profiler !== undefined
 }

package/src/domain/profiling/quotaCheck.ts

@@ -0,0 +1,89 @@
+import { fetch, setTimeout, clearTimeout } from '@kubesense/kubesense-browser-core'
+import { buildEndpointUrl } from '@kubesense/kubesense-js-core/transport'
+import type { RumConfiguration } from '@kubesense/kubesense-browser-rum-core'
+
+// Reason strings surfaced on RUM events. Backend reasons backend_unavailable and
+// backend_client_not_initialized are both normalised to backend_unavailable.
+export type BackendQuotaReason = 'quota_ok' | 'quota_exceeded' | 'org_disabled' | 'backend_unavailable' | 'undefined'
+
+// SDK-only reasons used when the backend is not reachable.
+export type FrontendQuotaReason = 'timeout' | 'api-error'
+
+export type QuotaReason = BackendQuotaReason | FrontendQuotaReason
+
+export interface QuotaResult {
+  decision: 'quota_ok' | 'quota_ko'
+  reason: QuotaReason
+}
+
+function parseQuotaResult(body: unknown, httpStatusFallback: QuotaResult): QuotaResult {
+  const attrs = (body as any)?.data?.attributes
+  if (!attrs || typeof attrs.admitted !== 'boolean' || typeof attrs.reason !== 'string') {
+    return httpStatusFallback
+  }
+  const reason: BackendQuotaReason =
+    attrs.reason === 'backend_client_not_initialized' ? 'backend_unavailable' : (attrs.reason as BackendQuotaReason)
+  return {
+    decision: attrs.admitted ? 'quota_ok' : 'quota_ko',
+    reason,
+  }
+}
+
+function buildQuotaUrl(configuration: RumConfiguration, sessionId: string): string {
+  return buildEndpointUrl({
+    proxy: configuration.proxy,
+    kubesenseRumEndpoint: configuration.kubesenseRumEndpoint,
+    path: '/rum/api/v1/profiling/quota',
+    parameters: `session_id=${sessionId}`,
+    subdomain: 'quota',
+  })
+}
+
+export function checkProfilingQuota(
+  configuration: RumConfiguration,
+  sessionId: string,
+  timeoutMs = 5000
+): Promise<QuotaResult> {
+  const url = buildQuotaUrl(configuration, sessionId)
+  const controller = new AbortController()
+
+  let timeoutId: ReturnType<typeof setTimeout>
+
+  const fetchPromise = fetch(url, {
+    credentials: 'omit',
+    signal: controller.signal,
+    headers: new Headers({
+      'DD-CLIENT-TOKEN': configuration.clientToken,
+    }),
+  })
+    .then((response) => {
+      const statusFallback: QuotaResult =
+        response.status === 429
+          ? { decision: 'quota_ko', reason: 'quota_exceeded' }
+          : { decision: 'quota_ok', reason: 'api-error' }
+      return response.json().then(
+        (body): QuotaResult => {
+          clearTimeout(timeoutId)
+          return parseQuotaResult(body, statusFallback)
+        },
+        (): QuotaResult => {
+          // Body unparseable — fall back to HTTP status
+          clearTimeout(timeoutId)
+          return statusFallback
+        }
+      )
+    })
+    .catch((): QuotaResult => {
+      clearTimeout(timeoutId)
+      return { decision: 'quota_ok', reason: 'api-error' }
+    })
+
+  const timeoutPromise = new Promise<QuotaResult>((resolve) => {
+    timeoutId = setTimeout(() => {
+      controller.abort()
+      resolve({ decision: 'quota_ok', reason: 'timeout' })
+    }, timeoutMs)
+  })
+
+  return Promise.race([fetchPromise, timeoutPromise])
+}

package/src/domain/profiling/test-utils/mockedTrace.ts

@@ -1,5 +1,4 @@
-import type { ProfilerTrace } from '../types'
-
+import type { ProfilerTrace } from '@kubesense/kubesense-js-core/util'
 const generateFiftyRandomSamples = () => {
   const samples = []
   for (let i = 0; i < 50; i++) {