⚗ [RUM-11393] Add Start/StopAction API

eslint.config.mjs

@@ -31,7 +31,7 @@ export default tseslint.config(
       'coverage',
       'rum-events-format',
       '.yarn',
-      'playwright-report',
+      '**/playwright-report',
       'docs',
       'developer-extension/.wxt',
       'developer-extension/.output',

packages/core/src/tools/experimentalFeatures.ts

@@ -19,6 +19,7 @@ export enum ExperimentalFeature {
   FEATURE_OPERATION_VITAL = 'feature_operation_vital',
   SHORT_SESSION_INVESTIGATION = 'short_session_investigation',
   AVOID_FETCH_KEEPALIVE = 'avoid_fetch_keepalive',
+  START_STOP_ACTION = 'start_stop_action',
   USE_CHANGE_RECORDS = 'use_change_records',
   SOURCE_CODE_CONTEXT = 'source_code_context',
 }

packages/rum-core/src/boot/preStartRum.spec.ts

@@ -10,6 +10,7 @@ import {
   DefaultPrivacyLevel,
   resetExperimentalFeatures,
   resetFetchObservable,
+  ExperimentalFeature,
 } from '@datadog/browser-core'
 import type { Clock } from '@datadog/browser-core/test'
 import {
@@ -18,13 +19,14 @@ import {
   mockClock,
   mockEventBridge,
   mockSyntheticsWorkerValues,
+  mockExperimentalFeatures,
 } from '@datadog/browser-core/test'
 import type { HybridInitConfiguration, RumConfiguration, RumInitConfiguration } from '../domain/configuration'
 import type { ViewOptions } from '../domain/view/trackViews'
 import { ActionType, VitalType } from '../rawRumEvent.types'
-import type { CustomAction } from '../domain/action/actionCollection'
 import type { RumPlugin } from '../domain/plugins'
 import { createCustomVitalsState } from '../domain/vital/vitalCollection'
+import type { CustomAction } from '../domain/action/trackCustomActions'
 import type { RumPublicApi, Strategy } from './rumPublicApi'
 import type { StartRumResult } from './startRum'
 import { createPreStartStrategy } from './preStartRum'
@@ -630,7 +632,7 @@ describe('preStartRum', () => {
       const addActionSpy = jasmine.createSpy()
       doStartRumSpy.and.returnValue({ addAction: addActionSpy } as unknown as StartRumResult)
 
-      const customAction: CustomAction = {
+      const customAction: Omit<CustomAction, 'id' | 'duration' | 'counts'> = {
         name: 'foo',
         type: ActionType.CUSTOM,
         startClocks: clocksNow(),
@@ -753,6 +755,41 @@ describe('preStartRum', () => {
       strategy.init(DEFAULT_INIT_CONFIGURATION, PUBLIC_API)
       expect(addOperationStepVitalSpy).toHaveBeenCalledOnceWith('foo', 'start', undefined, undefined)
     })
+
+    it('startAction / stopAction', () => {
+      mockExperimentalFeatures([ExperimentalFeature.START_STOP_ACTION])
+
+      const startActionSpy = jasmine.createSpy()
+      const stopActionSpy = jasmine.createSpy()
+      doStartRumSpy.and.returnValue({
+        startAction: startActionSpy,
+        stopAction: stopActionSpy,
+      } as unknown as StartRumResult)
+
+      strategy.startAction('user_login', { type: ActionType.CUSTOM })
+      strategy.stopAction('user_login')
+
+      strategy.init(DEFAULT_INIT_CONFIGURATION, PUBLIC_API)
+
+      expect(startActionSpy).toHaveBeenCalledWith(
+        'user_login',
+        jasmine.objectContaining({
+          type: ActionType.CUSTOM,
+        }),
+        jasmine.objectContaining({
+          relative: jasmine.any(Number),
+          timeStamp: jasmine.any(Number),
+        })
+      )
+      expect(stopActionSpy).toHaveBeenCalledWith(
+        'user_login',
+        undefined,
+        jasmine.objectContaining({
+          relative: jasmine.any(Number),
+          timeStamp: jasmine.any(Number),
+        })
+      )
+    })
   })
 
   describe('tracking consent', () => {

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

@@ -253,6 +253,16 @@ export function createPreStartStrategy(
       bufferApiCalls.add((startRumResult) => startRumResult.addAction(action))
     },
 
+    startAction(name, options) {
+      const startClocks = clocksNow()
+      bufferApiCalls.add((startRumResult) => startRumResult.startAction(name, options, startClocks))
+    },
+
+    stopAction(name, options) {
+      const stopClocks = clocksNow()
+      bufferApiCalls.add((startRumResult) => startRumResult.stopAction(name, options, stopClocks))
+    },
+
     addError(providedError) {
       bufferApiCalls.add((startRumResult) => startRumResult.addError(providedError))
     },

packages/rum-core/src/boot/rumPublicApi.spec.ts

@@ -36,6 +36,8 @@ const noopStartRum = (): ReturnType<StartRum> => ({
   hooks: {} as any,
   telemetry: {} as any,
   addOperationStepVital: () => undefined,
+  startAction: () => undefined,
+  stopAction: () => undefined,
 })
 const DEFAULT_INIT_CONFIGURATION = { applicationId: 'xxx', clientToken: 'xxx' }
 const FAKE_WORKER = {} as DeflateWorker
@@ -756,6 +758,72 @@ describe('rum public api', () => {
     })
   })
 
+  describe('startAction / stopAction', () => {
+    it('should call startAction and stopAction on the strategy', () => {
+      const startActionSpy = jasmine.createSpy()
+      const stopActionSpy = jasmine.createSpy()
+      const rumPublicApi = makeRumPublicApi(
+        () => ({
+          ...noopStartRum(),
+          startAction: startActionSpy,
+          stopAction: stopActionSpy,
+        }),
+        noopRecorderApi,
+        noopProfilerApi
+      )
+
+      rumPublicApi.init(DEFAULT_INIT_CONFIGURATION)
+      rumPublicApi.startAction('purchase', {
+        type: ActionType.CUSTOM,
+        context: { cart: 'abc' },
+      })
+      rumPublicApi.stopAction('purchase', {
+        context: { total: 100 },
+      })
+
+      expect(startActionSpy).toHaveBeenCalledWith(
+        'purchase',
+        jasmine.objectContaining({
+          type: ActionType.CUSTOM,
+          context: { cart: 'abc' },
+        })
+      )
+      expect(stopActionSpy).toHaveBeenCalledWith(
+        'purchase',
+        jasmine.objectContaining({
+          context: { total: 100 },
+        })
+      )
+    })
+
+    it('should sanitize startAction and stopAction inputs', () => {
+      const startActionSpy = jasmine.createSpy()
+      const rumPublicApi = makeRumPublicApi(
+        () => ({
+          ...noopStartRum(),
+          startAction: startActionSpy,
+        }),
+        noopRecorderApi,
+        noopProfilerApi
+      )
+
+      rumPublicApi.init(DEFAULT_INIT_CONFIGURATION)
+      rumPublicApi.startAction('action_name', {
+        type: ActionType.CUSTOM,
+        context: { count: 123, nested: { foo: 'bar' } } as any,
+        actionKey: 'action_key',
+      })
+
+      expect(startActionSpy.calls.argsFor(0)[1]).toEqual(
+        jasmine.objectContaining({
+          type: ActionType.CUSTOM,
+          context: { count: 123, nested: { foo: 'bar' } },
+          actionKey: 'action_key',
+        })
+      )
+    })
+  })
+
   describe('addDurationVital', () => {
     it('should call addDurationVital on the startRum result', () => {
       const addDurationVitalSpy = jasmine.createSpy()

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

@@ -53,6 +53,7 @@ import { callPluginsMethod } from '../domain/plugins'
 import type { Hooks } from '../domain/hooks'
 import type { SdkName } from '../domain/contexts/defaultContext'
 import type { LongTaskContexts } from '../domain/longTask/longTaskCollection'
+import type { ActionOptions } from '../domain/action/trackCustomActions'
 import { createPreStartStrategy } from './preStartRum'
 import type { StartRum, StartRumResult } from './startRum'
 
@@ -168,6 +169,24 @@ export interface RumPublicApi extends PublicApi {
    */
   addAction: (name: string, context?: object) => void
 
+  /**
+   * [Experimental] start a custom action, stored in `@action`
+   *
+   * @category Data Collection
+   * @param name - Name of the action
+   * @param options - Options of the action
+   */
+  startAction: (name: string, options?: ActionOptions) => void
+
+  /**
+   * [Experimental] stop a custom action, stored in `@action`
+   *
+   * @category Data Collection
+   * @param name - Name of the action
+   * @param options - Options of the action
+   */
+  stopAction: (name: string, options?: ActionOptions) => void
+
   /**
    * Add a custom error, stored in `@error`.
    *
@@ -523,6 +542,8 @@ export interface Strategy {
   accountContext: ContextManager
 
   addAction: StartRumResult['addAction']
+  startAction: StartRumResult['startAction']
+  stopAction: StartRumResult['stopAction']
   addError: StartRumResult['addError']
   addFeatureFlagEvaluation: StartRumResult['addFeatureFlagEvaluation']
   startDurationVital: StartRumResult['startDurationVital']
@@ -653,6 +674,24 @@ export function makeRumPublicApi(
       })
     },
 
+    startAction: monitor((name, options) => {
+      // addTelemetryUsage({ feature: 'start-action' })
+      strategy.startAction(sanitize(name)!, {
+        type: sanitize(options && options.type) as ActionType | undefined,
+        context: sanitize(options && options.context) as Context,
+        actionKey: options && options.actionKey,
+      })
+    }),
+
+    stopAction: monitor((name, options) => {
+      // addTelemetryUsage({ feature: 'stop-action' })
+      strategy.stopAction(sanitize(name)!, {
+        type: sanitize(options && options.type) as ActionType | undefined,
+        context: sanitize(options && options.context) as Context,
+        actionKey: options && options.actionKey,
+      })
+    }),
+
     addError: (error, context) => {
       const handlingStack = createHandlingStack('error')
       callMonitored(() => {

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

@@ -258,6 +258,8 @@ export function startRumEventCollection(
 
   return {
     addAction: actionCollection.addAction,
+    startAction: actionCollection.startAction,
+    stopAction: actionCollection.stopAction,
     addEvent: eventCollection.addEvent,
     addError,
     addTiming,

packages/rum-core/src/domain/action/actionCollection.spec.ts

@@ -9,9 +9,9 @@ import { LifeCycle, LifeCycleEventType } from '../lifeCycle'
 import type { AssembleHookParams, DefaultTelemetryEventAttributes, Hooks } from '../hooks'
 import { createHooks } from '../hooks'
 import type { RumMutationRecord } from '../../browser/domMutationObservable'
-import type { ActionContexts } from './actionCollection'
 import { LONG_TASK_START_TIME_CORRECTION, startActionCollection } from './actionCollection'
 import { ActionNameSource } from './actionNameConstants'
+import type { ActionContexts } from './trackAction'
 
 describe('actionCollection', () => {
   const lifeCycle = new LifeCycle()