@kubesense/kubesense-browser-rum 1.0.0

package/src/domain/profiling/profiler.ts

@@ -0,0 +1,338 @@
+import type { Encoder } from '@kubesense/kubesense-browser-core'
+import {
+  addEventListener,
+  clearTimeout,
+  setTimeout,
+  DOM_EVENT,
+  monitorError,
+  display,
+  getGlobalObject,
+  clocksOrigin,
+  clocksNow,
+  elapsed,
+  DeflateEncoderStreamId,
+} from '@kubesense/kubesense-browser-core'
+
+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,
+  RUMProfiler,
+  RUMProfilerConfiguration,
+  RumProfilerStoppedInstance,
+  RumViewEntry,
+} from './types'
+import { getNumberOfSamples } from './utils/getNumberOfSamples'
+import type { ProfilingContextManager } from './profilingContext'
+import { getCustomOrDefaultViewName } from './utils/getCustomOrDefaultViewName'
+import { assembleProfilingPayload } from './transport/assembly'
+
+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,
+  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)
+
+  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> = []
+
+  let instance: RumProfilerInstance = { state: 'stopped', stateReason: 'initializing' }
+
+  // Stops the profiler when session expires
+  lifeCycle.subscribe(LifeCycleEventType.SESSION_EXPIRED, () => {
+    stopProfiling('session-expired').catch(monitorError)
+  })
+
+  // 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.
+    }
+  })
+
+  // Public API to start the profiler.
+  function start(): void {
+    if (instance.state === 'running') {
+      return
+    }
+
+    const viewEntry = viewHistory.findView()
+
+    // Add initial view
+    // Note: `viewEntry.name` is only filled when users use manual view creation via `startView` method.
+    lastViewEntry = viewEntry
+      ? {
+          startClocks: viewEntry.startClocks,
+          viewId: viewEntry.id,
+          viewName: getCustomOrDefaultViewName(viewEntry.name, document.location.pathname),
+        }
+      : undefined
+
+    // 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
+    )
+
+    // Start profiler instance
+    startNextProfilerInstance()
+  }
+
+  // Public API to manually stop the profiler.
+  async function stop() {
+    await stopProfiling('stopped-by-user')
+  }
+
+  async function stopProfiling(reason: RumProfilerStoppedInstance['stateReason']) {
+    // Stop current profiler instance
+    await stopProfilerInstance(reason)
+
+    // Cleanup global listeners
+    globalCleanupTasks.forEach((task) => task())
+
+    // Update Profiling status once the Profiler has been stopped.
+    profilingContextManager.set({ status: 'stopped', error_reason: undefined })
+  }
+
+  /**
+   * Whenever a new Profiler instance is started, we need to add event listeners to surroundings (RUM Events, Long Tasks, etc) to enrich the Profiler data.
+   * If the instance is already running, we can keep the same event listeners.
+   */
+  function addEventListeners(existingInstance: RumProfilerInstance) {
+    if (existingInstance.state === 'running') {
+      // Instance is already running, so we can keep same event listeners.
+      return {
+        cleanupTasks: existingInstance.cleanupTasks,
+      }
+    }
+
+    // Store clean-up tasks for this instance (tasks to be executed when the Profiler is stopped or paused.)
+    const cleanupTasks = []
+
+    // Whenever the View is updated, we add a views entry to the profiler instance.
+    const viewUpdatedSubscription = lifeCycle.subscribe(LifeCycleEventType.VIEW_CREATED, (view) => {
+      const viewEntry = {
+        viewId: view.id,
+        // Note: `viewName` is only filled when users use manual view creation via `startView` method.
+        viewName: getCustomOrDefaultViewName(view.name, document.location.pathname),
+        startClocks: view.startClocks,
+      }
+
+      collectViewEntry(viewEntry)
+
+      // Update last view entry
+      lastViewEntry = viewEntry
+    })
+    cleanupTasks.push(viewUpdatedSubscription.unsubscribe)
+
+    return {
+      cleanupTasks,
+    }
+  }
+
+  function startNextProfilerInstance(): void {
+    // These APIs might be unavailable in some browsers
+    const globalThisProfiler: Profiler | undefined = getGlobalObject<any>().Profiler
+
+    if (!globalThisProfiler) {
+      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)
+
+    const { cleanupTasks } = addEventListeners(instance)
+
+    let profiler: Profiler
+    try {
+      // We have to create new Profiler each time we start a new instance
+      profiler = new globalThisProfiler({
+        sampleInterval: profilerConfiguration.sampleIntervalMs,
+        // Keep buffer size at 1.5 times of minimum required to collect data for a profiling instance
+        maxBufferSize: Math.round(
+          (profilerConfiguration.collectIntervalMs * 1.5) / profilerConfiguration.sampleIntervalMs
+        ),
+      })
+    } catch (e) {
+      if (e instanceof Error && e.message.includes('disabled by Document Policy')) {
+        // Missing Response Header (`js-profiling`) that is required to enable the profiler.
+        // We should suggest the user to enable the Response Header in their server configuration.
+        display.warn(
+          '[KUBESENSE_SDK] Profiler startup failed. Ensure your server includes the `Document-Policy: js-profiling` response header when serving HTML pages.',
+          e
+        )
+        profilingContextManager.set({ status: 'error', error_reason: 'missing-document-policy-header' })
+      } else {
+        profilingContextManager.set({ status: 'error', error_reason: 'unexpected-exception' })
+      }
+      return
+    }
+
+    profilingContextManager.set({ status: 'running', error_reason: undefined })
+
+    // Kick-off the new instance
+    instance = {
+      state: 'running',
+      startClocks: clocksNow(),
+      profiler,
+      timeoutId: setTimeout(startNextProfilerInstance, profilerConfiguration.collectIntervalMs),
+      views: [],
+      cleanupTasks,
+      longTasks: [],
+    }
+
+    // Add last view entry
+    collectViewEntry(lastViewEntry)
+
+    // Add event handler case we overflow the buffer
+    profiler.addEventListener('samplebufferfull', handleSampleBufferFull)
+  }
+
+  async function collectProfilerInstance(lastInstance: RumProfilerInstance) {
+    if (lastInstance.state !== 'running') {
+      return
+    }
+
+    // Cleanup instance
+    clearTimeout(lastInstance.timeoutId)
+    lastInstance.profiler.removeEventListener('samplebufferfull', handleSampleBufferFull)
+
+    // Store instance data snapshot in local variables to use in async callback
+    const { startClocks, views } = lastInstance
+
+    // Stop current profiler to get trace
+    await lastInstance.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)) {
+          // 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, {
+            startClocks,
+            endClocks,
+            clocksOrigin: clocksOrigin(),
+            longTasks,
+            views,
+            sampleInterval: profilerConfiguration.sampleIntervalMs,
+          })
+        )
+      })
+      .catch(monitorError)
+  }
+
+  async function stopProfilerInstance(stateReason: RumProfilerStoppedInstance['stateReason']) {
+    if (instance.state !== 'running') {
+      return
+    }
+    await onPauseOrStopProfilerInstance()
+    instance = { state: 'stopped', stateReason }
+  }
+
+  async function pauseProfilerInstance() {
+    if (instance.state !== 'running') {
+      return
+    }
+    await onPauseOrStopProfilerInstance()
+    instance = { state: 'paused' }
+  }
+
+  async function onPauseOrStopProfilerInstance() {
+    if (instance.state !== 'running') {
+      return
+    }
+    // Cleanup tasks
+    instance.cleanupTasks.forEach((cleanupTask) => cleanupTask())
+
+    await collectProfilerInstance(instance)
+  }
+
+  function collectViewEntry(viewEntry: RumViewEntry | undefined): void {
+    if (instance.state !== 'running' || !viewEntry) {
+      return
+    }
+
+    // Add entry to views
+    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 handleSampleBufferFull(): void {
+    startNextProfilerInstance()
+  }
+
+  function handleVisibilityChange(): void {
+    if (document.visibilityState === 'hidden' && instance.state === 'running') {
+      // Pause when tab is hidden. We use paused state to distinguish between
+      // 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)
+    } else if (document.visibilityState === 'visible' && instance.state === 'paused') {
+      // Resume when tab becomes visible again
+      startNextProfilerInstance()
+    }
+  }
+
+  function handleBeforeUnload(): void {
+    // `unload` can in some cases be triggered while the page is still active (link to a different protocol like mailto:).
+    // We can immediately flush (by starting a new profiler instance) to make sure we receive the data, and at the same time keep the profiler active.
+    // In case of the regular unload, the profiler will be shut down anyway.
+    startNextProfilerInstance()
+  }
+
+  function isStopped() {
+    return instance.state === 'stopped'
+  }
+
+  function isRunning() {
+    return instance.state === 'running'
+  }
+
+  function isPaused() {
+    return instance.state === 'paused'
+  }
+
+  return { start, stop, isStopped, isRunning, isPaused }
+}

package/src/domain/profiling/profilingContext.ts

@@ -0,0 +1,34 @@
+import { HookNames, SKIPPED } from '@kubesense/kubesense-browser-core'
+import type { Hooks, ProfilingInternalContextSchema } from '@kubesense/kubesense-browser-rum-core'
+import { RumEventType } from '@kubesense/kubesense-browser-rum-core'
+
+export interface ProfilingContextManager {
+  set: (next: ProfilingInternalContextSchema) => void
+  get: () => ProfilingInternalContextSchema | undefined
+}
+
+export function startProfilingContext(hooks: Hooks): ProfilingContextManager {
+  let currentContext: ProfilingInternalContextSchema = {
+    status: 'starting',
+  }
+
+  hooks.register(HookNames.Assemble, ({ eventType }) => {
+    if (eventType !== RumEventType.VIEW && eventType !== RumEventType.LONG_TASK) {
+      return SKIPPED
+    }
+
+    return {
+      type: eventType,
+      _kubesense: {
+        profiling: currentContext,
+      },
+    }
+  })
+
+  return {
+    get: () => currentContext,
+    set: (newContext: ProfilingInternalContextSchema) => {
+      currentContext = newContext
+    },
+  }
+}

package/src/domain/profiling/profilingSupported.ts

@@ -0,0 +1,10 @@
+import { getGlobalObject } from '@kubesense/kubesense-browser-core'
+import type { Profiler } from './types'
+
+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
+}

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

@@ -0,0 +1,58 @@
+import type { ProfilerTrace } from '../types'
+
+const generateFiftyRandomSamples = () => {
+  const samples = []
+  for (let i = 0; i < 50; i++) {
+    samples.push({
+      timestamp: i,
+      stackId: i % 3,
+    })
+  }
+  return samples
+}
+
+// eslint-disable-next-line local-rules/disallow-side-effects
+const randomSamples = generateFiftyRandomSamples()
+
+export const mockedEmptyTrace: ProfilerTrace = {
+  resources: [],
+  frames: [],
+  stacks: [],
+  samples: [],
+}
+
+export const mockedTrace: ProfilerTrace = {
+  resources: ['resource1', 'resource2', 'resource3'],
+  frames: [
+    {
+      name: 'frame-0',
+      line: 1,
+      column: 1,
+      resourceId: 0,
+    },
+    {
+      name: 'frame-1',
+      line: 2,
+      column: 2,
+      resourceId: 1,
+    },
+    {
+      name: 'frame-2',
+      line: 3,
+      column: 3,
+      resourceId: 2,
+    },
+  ],
+  stacks: [
+    {
+      frameId: 0,
+    },
+    {
+      frameId: 1,
+    },
+    {
+      frameId: 2,
+    },
+  ],
+  samples: randomSamples,
+}

package/src/domain/profiling/transport/assembly.ts

@@ -0,0 +1,78 @@
+import { buildTags, currentDrift } from '@kubesense/kubesense-browser-core'
+import type { RumConfiguration } from '@kubesense/kubesense-browser-rum-core'
+import type { RumProfilerTrace } from '../types'
+import { buildProfileEventAttributes } from './buildProfileEventAttributes'
+import type { ProfileEventAttributes } from './buildProfileEventAttributes'
+
+export interface ProfileEvent extends ProfileEventAttributes {
+  attachments: string[]
+  start: string // ISO date
+  end: string // ISO date
+  family: 'chrome'
+  runtime: 'chrome'
+  format: 'json'
+  version: 4
+  tags_profiler: string
+  _kubesense: {
+    clock_drift: number
+  }
+}
+
+export interface ProfileEventPayload {
+  event: ProfileEvent
+  'wall-time.json': RumProfilerTrace
+}
+
+export function assembleProfilingPayload(
+  profilerTrace: RumProfilerTrace,
+  configuration: RumConfiguration,
+  sessionId: string | undefined
+): ProfileEventPayload {
+  const event = buildProfileEvent(profilerTrace, configuration, sessionId)
+
+  return {
+    event,
+    'wall-time.json': profilerTrace,
+  }
+}
+
+function buildProfileEvent(
+  profilerTrace: RumProfilerTrace,
+  configuration: RumConfiguration,
+  sessionId: string | undefined
+): ProfileEvent {
+  const tags = buildTags(configuration) // TODO: get that from the tagContext hook
+  const profileAttributes = buildProfileEventAttributes(profilerTrace, configuration.applicationId, sessionId)
+  const profileEventTags = buildProfileEventTags(tags)
+
+  const profileEvent: ProfileEvent = {
+    ...profileAttributes,
+    attachments: ['wall-time.json'],
+    start: new Date(profilerTrace.startClocks.timeStamp).toISOString(),
+    end: new Date(profilerTrace.endClocks.timeStamp).toISOString(),
+    family: 'chrome',
+    runtime: 'chrome',
+    format: 'json',
+    version: 4, // Ingestion event version (not the version application tag)
+    tags_profiler: profileEventTags.join(','),
+    _kubesense: {
+      clock_drift: currentDrift(),
+    },
+  }
+
+  return profileEvent
+}
+
+/**
+ * Builds tags for the Profile Event.
+ *
+ * @param tags - RUM tags
+ * @returns Combined tags for the Profile Event.
+ */
+function buildProfileEventTags(tags: string[]): string[] {
+  // Tags already contains the common tags for all events. (service, env, version, etc.)
+  // Here we are adding some specific-to-profiling tags.
+  const profileEventTags = tags.concat(['language:javascript', 'runtime:chrome', 'family:chrome', 'host:browser'])
+
+  return profileEventTags
+}

package/src/domain/profiling/transport/buildProfileEventAttributes.ts

@@ -0,0 +1,66 @@
+import type { RumProfilerTrace, RumViewEntry } from '../types'
+
+export interface ProfileEventAttributes {
+  application: { id: string }
+  session?: { id: string }
+  view?: { id: string[]; name: string[] }
+  long_task?: { id: string[] }
+}
+
+/**
+ * Builds attributes for the Profile Event.
+ *
+ * @param profilerTrace - Profiler trace
+ * @param applicationId - application id.
+ * @param sessionId - session id.
+ * @returns Additional attributes.
+ */
+export function buildProfileEventAttributes(
+  profilerTrace: RumProfilerTrace,
+  applicationId: string,
+  sessionId: string | undefined
+): ProfileEventAttributes {
+  const attributes: ProfileEventAttributes = {
+    application: {
+      id: applicationId,
+    },
+  }
+  if (sessionId) {
+    attributes.session = {
+      id: sessionId,
+    }
+  }
+
+  // Extract view ids and names from the profiler trace and add them as attributes of the profile event.
+  // This will be used to filter the profiles by @view.id and/or @view.name.
+  const { ids, names } = extractViewIdsAndNames(profilerTrace.views)
+
+  if (ids.length) {
+    attributes.view = {
+      id: ids,
+      name: names,
+    }
+  }
+  const longTaskIds: string[] = profilerTrace.longTasks.map((longTask) => longTask.id).filter((id) => id !== undefined)
+
+  if (longTaskIds.length) {
+    attributes.long_task = { id: longTaskIds }
+  }
+  return attributes
+}
+
+function extractViewIdsAndNames(views: RumViewEntry[]): { ids: string[]; names: string[] } {
+  const result: { ids: string[]; names: string[] } = { ids: [], names: [] }
+  for (const view of views) {
+    result.ids.push(view.viewId)
+
+    if (view.viewName) {
+      result.names.push(view.viewName)
+    }
+  }
+
+  // Remove duplicates
+  result.names = Array.from(new Set(result.names))
+
+  return result
+}

package/src/domain/profiling/types/index.ts

@@ -0,0 +1,2 @@
+export type * from './profilerApi.types'
+export type * from './rumProfiler.types'

package/src/domain/profiling/types/profilerApi.types.ts

@@ -0,0 +1,87 @@
+// Define types for the new Profiler API
+// https://wicg.github.io/js-self-profiling/
+
+export interface ProfilerFrame {
+  /** A function instance name. */
+  readonly name: string
+  /** Index in the trace.resources array. */
+  readonly resourceId?: number
+  /** 1-based index of the line. */
+  readonly line?: number
+  /** 1-based index of the column. */
+  readonly column?: number
+}
+
+export interface ProfilerStack {
+  /** Index in the trace.stacks array. */
+  readonly parentId?: number
+  /** Index in the trace.frames array. */
+  readonly frameId: number
+}
+
+export interface ProfilerSample {
+  /** High resolution time relative to the profiling session's time origin. */
+  readonly timestamp: number
+  /** Index in the trace.stacks array. */
+  readonly stackId?: number
+}
+
+export type ProfilerResource = string
+
+export interface ProfilerTrace {
+  /** An array of profiler resources. */
+  readonly resources: ProfilerResource[]
+  /** An array of profiler frames. */
+  readonly frames: ProfilerFrame[]
+  /** An array of profiler stacks. */
+  readonly stacks: ProfilerStack[]
+  /** An array of profiler samples. */
+  readonly samples: ProfilerSample[]
+}
+
+export interface ProfilerInitOptions {
+  /** Sample interval in ms. */
+  readonly sampleInterval: number
+  /** Max buffer size in number of samples. */
+  readonly maxBufferSize: number
+}
+
+export interface Profiler extends EventTarget {
+  /** Sample interval in ms. */
+  readonly sampleInterval: number
+  /** True if profiler is stopped. */
+  readonly stopped: boolean
+
+  // eslint-disable-next-line @typescript-eslint/no-misused-new
+  new (options: ProfilerInitOptions): Profiler
+  stop(): Promise<ProfilerTrace>
+
+  addEventListener<K extends keyof ProfilerEventMap>(
+    type: K,
+    listener: (this: typeof globalThis, ev: ProfilerEventMap[K]) => any,
+    options?: boolean | AddEventListenerOptions
+  ): void
+  addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions
+  ): void
+  removeEventListener<K extends keyof ProfilerEventMap>(
+    type: K,
+    listener: (this: typeof globalThis, ev: ProfilerEventMap[K]) => any,
+    options?: boolean | EventListenerOptions
+  ): void
+  removeEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | EventListenerOptions
+  ): void
+}
+
+interface ProfilerEventMap {
+  samplebufferfull: SampleBufferFullEvent
+}
+
+export interface SampleBufferFullEvent extends Event {
+  readonly target: Profiler
+}