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

package/src/domain/segmentCollection/segmentCollection.ts

@@ -1,6 +1,7 @@
-import type { DeflateEncoder, HttpRequest, TimeoutId } from '@kubesense/kubesense-browser-core'
-import { isPageExitReason, ONE_SECOND, clearTimeout, setTimeout } from '@kubesense/kubesense-browser-core'
-import type { LifeCycle, ViewHistory, RumSessionManager, RumConfiguration } from '@kubesense/kubesense-browser-rum-core'
+import type { DeflateEncoder, HttpRequest, TimeoutId, SessionManager } from '@kubesense/kubesense-browser-core'
+import { ONE_SECOND } from '@kubesense/kubesense-js-core/time'
+import { isPageExitReason, PageExitReason, clearTimeout, setTimeout } from '@kubesense/kubesense-browser-core'
+import type { LifeCycle, ViewHistory, RumConfiguration } from '@kubesense/kubesense-browser-rum-core'
 import { LifeCycleEventType } from '@kubesense/kubesense-browser-rum-core'
 import type { BrowserRecord, CreationReason, SegmentContext } from '../../types'
 import type { SerializationStats } from '../record'
@@ -50,7 +51,7 @@ interface SegmentCollector {
 export function startSegmentCollection(
   lifeCycle: LifeCycle,
   configuration: RumConfiguration,
-  sessionManager: RumSessionManager,
+  sessionManager: SessionManager,
   viewHistory: ViewHistory,
   httpRequest: HttpRequest<ReplayPayload>,
   encoder: DeflateEncoder
@@ -98,9 +99,9 @@ export function doStartSegmentCollection(
   })
 
   const { unsubscribe: unsubscribePageMayExit } = lifeCycle.subscribe(
-    LifeCycleEventType.PAGE_MAY_EXIT,
-    (pageMayExitEvent) => {
-      flushSegment(pageMayExitEvent.reason as FlushReason)
+    LifeCycleEventType.PREPARE_URGENT_FLUSH,
+    (reason) => {
+      flushSegment(reason as FlushReason)
     }
   )
 
@@ -109,7 +110,11 @@ export function doStartSegmentCollection(
       state.segment.flush((metadata, stats, encoderResult) => {
         const payload = buildReplayPayload(encoderResult.output, metadata, stats, encoderResult.rawBytesCount)
 
-        if (isPageExitReason(flushReason)) {
+        // sendOnExit() is less reliable than send() since it doesn't retry. If the page is
+        // *really* about to close, sendOnExit() is still better, since it uses a mechanism
+        // that outlives the page itself; for PageExitReason.HIDDEN, though, the page is
+        // probably not actually closing, so we prefer send().
+        if (isPageExitReason(flushReason) && flushReason !== PageExitReason.HIDDEN) {
           httpRequest.sendOnExit(payload)
         } else {
           httpRequest.send(payload)
@@ -172,11 +177,7 @@ export function doStartSegmentCollection(
   }
 }
 
-export function computeSegmentContext(
-  applicationId: string,
-  sessionManager: RumSessionManager,
-  viewHistory: ViewHistory
-) {
+export function computeSegmentContext(applicationId: string, sessionManager: SessionManager, viewHistory: ViewHistory) {
   const session = sessionManager.findTrackedSession()
   const viewContext = viewHistory.findView()
   if (!session || !viewContext) {

package/src/domain/segmentCollection/startDroppedSegmentRecovery.ts

@@ -0,0 +1,37 @@
+import type { HttpRequestEvent, Observable } from '@kubesense/kubesense-browser-core'
+import { elapsed, ONE_SECOND, timeStampNow } from '@kubesense/kubesense-js-core/time'
+import type { TimeStamp } from '@kubesense/kubesense-js-core/time'
+import type { ReplayPayload } from './buildReplayPayload'
+
+/** The least time between two recovery snapshots. */
+export const DROPPED_SEGMENT_RECOVERY_INTERVAL = 30 * ONE_SECOND
+
+/**
+ * Takes a new full snapshot when a segment is lost to a network error.
+ *
+ * Every record after a lost segment builds on DOM the intake never received, so without a new
+ * snapshot the replay freezes on the last DOM it has until the next view starts one. Only a
+ * network error triggers it — an upload the intake rejected (401, 413) would see the snapshot
+ * rejected too — and at most once per interval, so a failing network costs one snapshot per
+ * interval rather than one per segment.
+ */
+export function startDroppedSegmentRecovery(
+  replayRequestObservable: Observable<HttpRequestEvent<ReplayPayload>>,
+  takeFullSnapshot: () => void
+) {
+  let lastRecovery: TimeStamp | undefined
+
+  const { unsubscribe } = replayRequestObservable.subscribe((event) => {
+    if (event.type !== 'dropped' || event.status !== 0) {
+      return
+    }
+    const now = timeStampNow()
+    if (lastRecovery !== undefined && elapsed(lastRecovery, now) < DROPPED_SEGMENT_RECOVERY_INTERVAL) {
+      return
+    }
+    lastRecovery = now
+    takeFullSnapshot()
+  })
+
+  return { stop: unsubscribe }
+}

package/src/domain/segmentCollection/startSegmentTelemetry.ts

@@ -1,4 +1,10 @@
-import type { BandwidthStats, Context, HttpRequestEvent, Observable, Telemetry } from '@kubesense/kubesense-browser-core'
+import type {
+  BandwidthStats,
+  Context,
+  HttpRequestEvent,
+  Observable,
+  Telemetry,
+} from '@kubesense/kubesense-browser-core'
 import { TelemetryMetrics, addTelemetryMetrics, noop } from '@kubesense/kubesense-browser-core'
 import type { ReplayPayload } from './buildReplayPayload'
 
@@ -8,6 +14,10 @@ interface SegmentMetrics extends Context {
     max: number
     sum: number
   }
+  encoding: {
+    fullSnapshot: 'v1' | 'change'
+    incrementalSnapshot: 'v1' | 'change'
+  }
   isFullSnapshot: boolean
   ongoingRequests: {
     count: number
@@ -41,7 +51,7 @@ export function startSegmentTelemetry(
       (requestEvent.type === 'success' && requestEvent.payload.isFullSnapshot)
     ) {
       const metrics = createSegmentMetrics(requestEvent.type, requestEvent.bandwidth, requestEvent.payload)
-      // monitor-until: 2026-07-01
+      // monitor-until: forever
       addTelemetryMetrics(TelemetryMetrics.SEGMENT_METRICS_TELEMETRY_NAME, { metrics })
     }
   })
@@ -62,6 +72,10 @@ function createSegmentMetrics(
       max: payload.cssText.max,
       sum: payload.cssText.sum,
     },
+    encoding: {
+      fullSnapshot: 'change',
+      incrementalSnapshot: 'change',
+    },
     isFullSnapshot: payload.isFullSnapshot,
     ongoingRequests: {
       count: bandwidthStats.ongoingRequestCount,

package/src/domain/startRecorderInitTelemetry.ts

@@ -1,5 +1,7 @@
-import type { Context, Duration, Telemetry, Observable, TimeStamp } from '@kubesense/kubesense-browser-core'
-import { TelemetryMetrics, addTelemetryMetrics, noop, timeStampNow, elapsed } from '@kubesense/kubesense-browser-core'
+import type { Context, Telemetry, Observable } from '@kubesense/kubesense-browser-core'
+import { elapsed, timeStampNow } from '@kubesense/kubesense-js-core/time'
+import type { Duration, TimeStamp } from '@kubesense/kubesense-js-core/time'
+import { TelemetryMetrics, addTelemetryMetrics, noop } from '@kubesense/kubesense-browser-core'
 import type { RecorderInitEvent } from '../boot/postStartStrategy'
 
 type RecorderInitResult = 'aborted' | 'deflate-encoder-load-failed' | 'recorder-load-failed' | 'succeeded'
@@ -55,7 +57,7 @@ export function startRecorderInitTelemetry(telemetry: Telemetry, observable: Obs
         unsubscribe()
 
         if (startContext) {
-          // monitor-until: 2026-07-01
+          // monitor-until: forever
           addTelemetryMetrics(TelemetryMetrics.RECORDER_INIT_METRICS_TELEMETRY_NAME, {
             metrics: createRecorderInitMetrics(
               startContext.forced,

package/src/entries/internal.ts

@@ -5,7 +5,6 @@
  * WARNING: this module is not intended for public usages, and won't follow semver for breaking
  * changes.
  */
-export type { TimeStamp } from '@kubesense/kubesense-browser-core'
 export {
   PRIVACY_ATTR_NAME,
   PRIVACY_ATTR_VALUE_HIDDEN,
@@ -15,4 +14,16 @@ export {
 
 export * from '../types'
 
-export { takeFullSnapshot, takeNodeSnapshot, serializeNode as serializeNodeWithId } from '../domain/record'
+export { takeFullSnapshot, takeNodeSnapshot } from '../domain/record'
+
+/**
+ * The Change-format decoder, exported so the Web app's replay player can resolve string-table
+ * references without reimplementing the encoding. Keeping the single copy here means a future SDK
+ * upgrade that changes the format updates the player through the same dependency bump, instead of
+ * leaving two implementations to drift apart.
+ */
+export type { ChangeDecoder, ChangeDecoderOptions } from '../domain/record'
+export { createChangeDecoder } from '../domain/record'
+
+export { makeRecorderApi } from '../boot/recorderApi'
+export { makeProfilerApi } from '../boot/profilerApi'

package/src/entries/internalSynthetics.ts

@@ -5,9 +5,8 @@
  * WARNING: this module is not intended for public usages, and won't follow semver for breaking
  * changes.
  */
-import { makeRumPublicApi, startRum } from '@kubesense/kubesense-browser-rum-core'
+import { makeRumPublicApi } from '@kubesense/kubesense-browser-rum-core'
 import { makeRecorderApi } from '../boot/recorderApi'
-import { lazyLoadRecorder } from '../boot/lazyLoadRecorder'
 import { makeProfilerApi } from '../boot/profilerApi'
 
 export { DefaultPrivacyLevel } from '@kubesense/kubesense-browser-core'
@@ -15,9 +14,9 @@ export { DefaultPrivacyLevel } from '@kubesense/kubesense-browser-core'
 // Disable the rule that forbids potential side effects, because we know that those functions don't
 // have side effects.
 /* eslint-disable local-rules/disallow-side-effects */
-const recorderApi = makeRecorderApi(lazyLoadRecorder)
+const recorderApi = makeRecorderApi()
 const profilerApi = makeProfilerApi()
-export const kubesenseSdk = makeRumPublicApi(startRum, recorderApi, profilerApi, {
+export const kubesenseSdk = makeRumPublicApi(recorderApi, profilerApi, {
   ignoreInitIfSyntheticsWillInjectRum: false,
   sdkName: 'rum-synthetics',
 })

package/src/entries/main.ts

@@ -1,18 +1,18 @@
 /**
- * Kubesense Browser RUM SDK - Full version with Session Replay and Real User Profiling capabilities.
+ * KubeSense Browser RUM SDK - Full version with Session Replay and Real User Profiling capabilities.
  * Use this package to monitor your web application's performance and user experience.
  *
  * @packageDocumentation
  * @see [RUM Browser Monitoring Setup](https://docs.kubesense.ai/real_user_monitoring/browser/)
  */
 
+import { globalObject } from '@kubesense/kubesense-js-core/util'
 // Keep the following in sync with packages/rum-slim/src/entries/main.ts
-import { defineGlobal, getGlobalObject } from '@kubesense/kubesense-browser-core'
+import { defineGlobal } from '@kubesense/kubesense-browser-core'
 import type { RumPublicApi } from '@kubesense/kubesense-browser-rum-core'
-import { makeRumPublicApi, startRum } from '@kubesense/kubesense-browser-rum-core'
+import { makeRumPublicApi } from '@kubesense/kubesense-browser-rum-core'
 import { makeRecorderApi } from '../boot/recorderApi'
 import { createDeflateEncoder, startDeflateWorker } from '../domain/deflate'
-import { lazyLoadRecorder } from '../boot/lazyLoadRecorder'
 import { makeProfilerApi } from '../boot/profilerApi'
 
 export type {
@@ -22,14 +22,13 @@ export type {
   SessionPersistence,
   TrackingConsent,
   MatchOption,
-  ProxyFn,
-  Site,
   Context,
   ContextValue,
   ContextArray,
   RumInternalContext,
 } from '@kubesense/kubesense-browser-core'
 export { DefaultPrivacyLevel } from '@kubesense/kubesense-browser-core'
+export type { ProxyFn, Site } from '@kubesense/kubesense-js-core/transport'
 
 /**
  * @deprecated Use {@link KubesenseSdk} instead
@@ -39,16 +38,24 @@ export type RumGlobal = RumPublicApi
 export type {
   RumPublicApi as KubesenseSdk,
   RumInitConfiguration,
+  RumBeforeSend,
   ViewOptions,
   StartRecordingOptions,
   AddDurationVitalOptions,
   DurationVitalOptions,
-  DurationVitalReference,
+  OperationOptions,
+  FeatureOperationOptions,
+  FailureReason,
+  ActionOptions,
+  ResourceOptions,
+  ResourceStopOptions,
   TracingOption,
   RumPlugin,
   OnRumStartOptions,
+  RumPluginOnInitOptions,
   PropagatorType,
   FeatureFlagsForEvents,
+  MatchHeader,
 
   // Events
   CommonProperties,
@@ -58,6 +65,7 @@ export type {
   RumLongTaskEvent,
   RumResourceEvent,
   RumViewEvent,
+  RumViewUpdateEvent,
   RumVitalEvent,
 
   // Events context
@@ -66,13 +74,14 @@ export type {
   RumErrorEventDomainContext,
   RumActionEventDomainContext,
   RumVitalEventDomainContext,
-  RumFetchResourceEventDomainContext,
-  RumXhrResourceEventDomainContext,
-  RumOtherResourceEventDomainContext,
+  RumResourceEventDomainContext,
+  RumWebSocketResourceEventDomainContext,
   RumLongTaskEventDomainContext,
 } from '@kubesense/kubesense-browser-rum-core'
 
-const recorderApi = makeRecorderApi(lazyLoadRecorder)
+export { DEFAULT_TRACKED_RESOURCE_HEADERS, CanvasRecordingQuality } from '@kubesense/kubesense-browser-rum-core'
+
+const recorderApi = makeRecorderApi()
 
 const profilerApi = makeProfilerApi()
 
@@ -83,13 +92,13 @@ const profilerApi = makeProfilerApi()
  * @see {@link KubesenseSdk}
  * @see [RUM Browser Monitoring Setup](https://docs.kubesense.ai/real_user_monitoring/browser/)
  */
-export const kubesenseSdk = makeRumPublicApi(startRum, recorderApi, profilerApi, {
+export const kubesenseSdk = makeRumPublicApi(recorderApi, profilerApi, {
   startDeflateWorker,
   createDeflateEncoder,
   sdkName: 'rum',
 })
 
-interface BrowserWindow extends Window {
+interface BrowserWindow {
   KUBESENSE_SDK?: RumPublicApi
 }
-defineGlobal(getGlobalObject<BrowserWindow>(), 'KUBESENSE_SDK', kubesenseSdk)
+defineGlobal(globalObject as BrowserWindow, 'KUBESENSE_SDK', kubesenseSdk)

package/src/types/index.ts

@@ -1,2 +1,3 @@
 export type * from './sessionReplay'
 export * from './sessionReplayConstants'
+export type * from './profiling'

package/src/types/profiling.ts

@@ -0,0 +1,315 @@
+/**
+ * DO NOT MODIFY IT BY HAND. Run `yarn json-schemas:sync` instead.
+ */
+
+/**
+ * Schema of Browser SDK Profiling types.
+ */
+export type BrowserProfiling = BrowserProfileEvent | BrowserProfilerTrace
+/**
+ * Schema of the Browser SDK Profile Event payload.
+ */
+export type BrowserProfileEvent = ProfileCommonProperties & {
+  /**
+   * Profile data format.
+   */
+  readonly format: 'json'
+  /**
+   * KubeSense internal metadata.
+   */
+  readonly _kubesense: {
+    /**
+     * Clock drift value. Used by Browser SDK.
+     */
+    readonly clock_drift: number
+  }
+  /**
+   * Action properties.
+   */
+  readonly action?: {
+    /**
+     * Array of action IDs.
+     */
+    readonly id: string[]
+    /**
+     * Array of action labels.
+     */
+    readonly label: string[]
+  }
+}
+
+/**
+ * Schema of a Profile Event metadata. Contains attributes shared by all profiles.
+ */
+export interface ProfileCommonProperties {
+  /**
+   * Application properties.
+   */
+  readonly application: {
+    /**
+     * Application ID.
+     */
+    readonly id: string
+  }
+  /**
+   * Session properties.
+   */
+  readonly session?: {
+    /**
+     * Session ID.
+     */
+    readonly id: string
+  }
+  /**
+   * View properties.
+   */
+  readonly view?: {
+    /**
+     * Array of view IDs.
+     */
+    readonly id: string[]
+    /**
+     * Array of view names.
+     */
+    readonly name: string[]
+  }
+  /**
+   * Long task properties.
+   */
+  readonly long_task?: {
+    /**
+     * Array of long task IDs.
+     */
+    readonly id: string[]
+  }
+  /**
+   * Vital properties.
+   */
+  readonly vital?: {
+    /**
+     * Array of vital IDs.
+     */
+    readonly id: string[]
+    /**
+     * Array of vital labels.
+     */
+    readonly label: string[]
+  }
+  /**
+   * List of attachment filenames.
+   */
+  readonly attachments: string[]
+  /**
+   * Start time as ISO 8601 date string (yyyy-MM-dd'T'HH:mm:ss.SSS'Z').
+   */
+  readonly start: string
+  /**
+   * End time marking when the profile ended, as ISO 8601 date string (yyyy-MM-dd'T'HH:mm:ss.SSS'Z').
+   */
+  readonly end: string
+  /**
+   * Profiler family.
+   */
+  readonly family: 'android' | 'chrome' | 'ios'
+  /**
+   * Runtime environment.
+   */
+  readonly runtime: 'android' | 'chrome' | 'ios'
+  /**
+   * Profile ingestion event version.
+   */
+  readonly version: number
+  /**
+   * Comma-separated profiler tags.
+   */
+  readonly tags_profiler: string
+}
+/**
+ * Schema of a RUM profiler trace containing profiling data enriched with RUM context.
+ */
+export interface BrowserProfilerTrace {
+  /**
+   * An array of profiler resources.
+   */
+  readonly resources: string[]
+  /**
+   * Mapping of profiler resources to their debug IDs for source map deobfuscation.
+   */
+  readonly debugIds?: ResourceDebugId[]
+  /**
+   * An array of profiler frames.
+   */
+  readonly frames: ProfilerFrame[]
+  /**
+   * An array of profiler stacks.
+   */
+  readonly stacks: ProfilerStack[]
+  /**
+   * An array of profiler samples.
+   */
+  readonly samples: ProfilerSample[]
+  startClocks: ClocksState
+  endClocks: ClocksState
+  clocksOrigin: ClocksState
+  /**
+   * Sample interval in milliseconds.
+   */
+  readonly sampleInterval: number
+  /**
+   * List of detected long tasks.
+   */
+  readonly longTasks: RumProfilerLongTaskEntry[]
+  /**
+   * List of detected vital entries.
+   */
+  readonly vitals?: RumProfilerVitalEntry[]
+  /**
+   * List of detected action entries.
+   */
+  readonly actions?: RumProfilerActionEntry[]
+  /**
+   * List of detected navigation entries.
+   */
+  readonly views: RumViewEntry[]
+}
+/**
+ * Association between a profiler resource and its debug ID.
+ */
+export interface ResourceDebugId {
+  /**
+   * Index in the trace.resources array.
+   */
+  readonly resourceId: number
+  /**
+   * Debug ID (UUID) for the resource, used for source map deobfuscation.
+   */
+  readonly debugId: string
+}
+/**
+ * Schema of a profiler frame from the JS Self-Profiling API.
+ */
+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
+}
+/**
+ * Schema of a profiler stack from the JS Self-Profiling API.
+ */
+export interface ProfilerStack {
+  /**
+   * Index in the trace.stacks array.
+   */
+  readonly parentId?: number
+  /**
+   * Index in the trace.frames array.
+   */
+  readonly frameId: number
+}
+/**
+ * Schema of a profiler sample from the JS Self-Profiling API.
+ */
+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
+}
+/**
+ * Schema of timing state with both relative and absolute timestamps.
+ */
+export interface ClocksState {
+  /**
+   * Time relative to navigation start in milliseconds.
+   */
+  readonly relative: number
+  /**
+   * Epoch time in milliseconds.
+   */
+  readonly timeStamp: number
+}
+/**
+ * Schema of a long task entry recorded during profiling.
+ */
+export interface RumProfilerLongTaskEntry {
+  /**
+   * RUM Long Task id.
+   */
+  readonly id?: string
+  /**
+   * Duration in ms of the long task or long animation frame.
+   */
+  readonly duration: number
+  /**
+   * Type of the event: long task or long animation frame
+   */
+  readonly entryType: 'longtask' | 'long-animation-frame'
+  startClocks: ClocksState
+}
+/**
+ * Schema of a vital entry recorded during profiling.
+ */
+export interface RumProfilerVitalEntry {
+  /**
+   * RUM Vital id.
+   */
+  readonly id: string
+  /**
+   * RUM Vital label.
+   */
+  readonly label: string
+  /**
+   * Duration in ms of the vital.
+   */
+  readonly duration?: number
+  startClocks: ClocksState
+}
+/**
+ * Schema of a action entry recorded during profiling.
+ */
+export interface RumProfilerActionEntry {
+  /**
+   * RUM Action id.
+   */
+  readonly id: string
+  /**
+   * RUM Action label.
+   */
+  readonly label: string
+  /**
+   * Duration in ms of the duration vital.
+   */
+  readonly duration?: number
+  startClocks: ClocksState
+}
+/**
+ * Schema of a RUM view entry recorded during profiling.
+ */
+export interface RumViewEntry {
+  startClocks: ClocksState
+  /**
+   * RUM view id.
+   */
+  readonly viewId: string
+  /**
+   * RUM view name.
+   */
+  readonly viewName?: string
+}