Interface DatadogRum

Public API for the RUM browser SDK.

See RUM Browser Monitoring Setup for further information.

interface DatadogRum {
    addAction: (name: string, context?: object) => void;
    addDurationVital: (name: string, options: AddDurationVitalOptions) => void;
    addError: (error: unknown, context?: object) => void;
    addFeatureFlagEvaluation: (key: string, value: any) => void;
    addTiming: (name: string, time?: number) => void;
    clearAccount: () => void;
    clearUser: () => void;
    DEFAULT_TRACKED_RESOURCE_HEADERS: readonly [
        "cache-control",
        "etag",
        "age",
        "expires",
        "content-type",
        "content-encoding",
        "vary",
        "content-length",
        "server-timing",
        "x-cache",
    ];
    failFeatureOperation: (
        name: string,
        failureReason: FailureReason,
        options?: OperationOptions,
    ) => void;
    failOperation: (
        name: string,
        failureReason: FailureReason,
        options?: OperationOptions,
    ) => void;
    getAccount: () => Context;
    getGlobalContext: () => Context;
    getInitConfiguration: () => RumInitConfiguration | undefined;
    getSessionReplayLink: () => string | undefined;
    getUser: () => Context;
    init: (initConfiguration: RumInitConfiguration) => void;
    onReady: (callback: () => void) => void;
    removeAccountProperty: (key: string) => void;
    removeGlobalContextProperty: (key: any) => void;
    removeUserProperty: (key: any) => void;
    setAccount: (newAccount: Account) => void;
    setAccountProperty: (key: string, property: any) => void;
    setGlobalContext: (context: Context) => void;
    setGlobalContextProperty: (key: any, value: any) => void;
    setTrackingConsent: (trackingConsent: TrackingConsent) => void;
    setUserProperty: (key: any, property: any) => void;
    setViewContext: (context: Context) => void;
    setViewContextProperty: (key: string, value: any) => void;
    setViewLoadingTime: () => void;
    setViewName: (name: string) => void;
    startAction: (name: string, options?: ActionOptions) => void;
    startDurationVital: (name: string, options?: DurationVitalOptions) => void;
    startFeatureOperation: (name: string, options?: OperationOptions) => void;
    startOperation: (name: string, options?: OperationOptions) => void;
    startResource: (url: string, options?: ResourceOptions) => void;
    startSessionReplayRecording: (options?: StartRecordingOptions) => void;
    stopAction: (name: string, options?: ActionOptions) => void;
    stopDurationVital: (name: string, options?: DurationVitalOptions) => void;
    stopResource: (url: string, options?: ResourceStopOptions) => void;
    stopSessionReplayRecording: () => void;
    succeedFeatureOperation: (name: string, options?: OperationOptions) => void;
    succeedOperation: (name: string, options?: OperationOptions) => void;
    version: string;
    clearGlobalContext(): void;
    getViewContext(): Context;
    setUser(newUser: User & { id: string }): void;
    setUser(newUser: User): void;
    startView(nameOrOptions?: string | ViewOptions): void;
    stopSession(): void;
}

Hierarchy (View Summary)

PublicApi
- DatadogRum

Index

Init

getInitConfiguration

getInitConfiguration: () => RumInitConfiguration | undefined

Get the init configuration

Type Declaration

- (): RumInitConfiguration | undefined
- Returns RumInitConfiguration | undefined
  RumInitConfiguration | undefined

init

init: (initConfiguration: RumInitConfiguration) => void

Init the RUM browser SDK.

See RUM Browser Monitoring Setup for further information.

Type Declaration

- (initConfiguration: RumInitConfiguration): void
- Parameters
  - initConfiguration: RumInitConfiguration
    Configuration options of the SDK
  Returns void

Example

datadogRum.init({
  applicationId: '<DATADOG_APPLICATION_ID>',
  clientToken: '<DATADOG_CLIENT_TOKEN>',
  site: '<DATADOG_SITE>',
  // ...
})

Privacy

setTrackingConsent

setTrackingConsent: (trackingConsent: TrackingConsent) => void

Set the tracking consent of the current user.

Data will be sent only if it is set to "granted". This value won't be stored by the library across page loads: you will need to call this method or set the appropriate trackingConsent field in the init() method at each page load.

If this method is called before the init() method, the provided value will take precedence over the one provided as initialization parameter.

See User tracking consent for further information.

Type Declaration

- (trackingConsent: TrackingConsent): void
- Parameters
  - trackingConsent: TrackingConsent
    The user tracking consent
  Returns void

Data Collection

addAction

addAction: (name: string, context?: object) => void

Add a custom action, stored in @action

See Send RUM Custom Actions for further information.

Type Declaration

- (name: string, context?: object): void
- Parameters
  - name: string
    Name of the action
  - Optionalcontext: object
    Context of the action
  Returns void

addError

addError: (error: unknown, context?: object) => void

Add a custom error, stored in @error.

See Send RUM Custom Actions for further information.

Type Declaration

- (error: unknown, context?: object): void
- Parameters
  - error: unknown
    Error. Favor sending a Javascript Error to have a stack trace attached to the error event.
  - Optionalcontext: object
    Context of the error
  Returns void

addFeatureFlagEvaluation

addFeatureFlagEvaluation: (key: string, value: any) => void

Add a feature flag evaluation, stored in @feature_flags.<feature_flag_key>

We recommend enabling the intake request compression when using feature flags compressIntakeRequests: true.

See Feature Flag Tracking for further information.

Type Declaration

- (key: string, value: any): void
- Parameters
  - key: string
    The key of the feature flag.
  - value: any
    The value of the feature flag.
  Returns void

addTiming

addTiming: (name: string, time?: number) => void

Add a custom timing relative to the start of the current view, stored in @view.custom_timings.<timing_name>

Note: passing a relative time is discouraged since it is actually used as-is but displayed relative to the view start. We currently don't provide a way to retrieve the view start time, so it can be challenging to provide a timing relative to the view start. see https://github.com/DataDog/browser-sdk/issues/2552

Type Declaration

- (name: string, time?: number): void
- Parameters
  - name: string
    Name of the custom timing
  - Optionaltime: number
    Epoch timestamp of the custom timing (if not set, will use current time)
  Returns void

setViewLoadingTime

setViewLoadingTime: () => void

[Experimental] Manually set the current view's loading time.

Call this method when the view has finished loading. The loading time is computed as the elapsed time since the view started. Each call replaces any previously set value (last-call-wins).

startAction

startAction: (name: string, options?: ActionOptions) => void

Start tracking a custom action.

Call stopAction with the same name (and optional actionKey) to send a RUM action event with the elapsed duration. Errors and resources triggered between start and stop are associated with the action.

Type Declaration

- (name: string, options?: ActionOptions): void
- Parameters
  - name: string
    Name of the action
  - Optionaloptions: ActionOptions
    Options of the action (@default type: 'custom')
  Returns void

Example

datadogRum.startAction('checkout', { context: { cartId: 'abc' } })
// ... user completes checkout
datadogRum.stopAction('checkout')

startResource

startResource: (url: string, options?: ResourceOptions) => void

Start tracking a resource manually.

Use this for network activity that the SDK cannot automatically instrument. Call stopResource with the same URL (and optional resourceKey) to send a RUM resource event with the elapsed duration.

Type Declaration

- (url: string, options?: ResourceOptions): void
- Parameters
  - url: string
    URL of the resource
  - Optionaloptions: ResourceOptions
    Options of the resource (@default type: 'other')
  Returns void

Example

datadogRum.startResource('https://api.example.com/users', { type: 'fetch', method: 'POST' })
// ... perform the request
datadogRum.stopResource('https://api.example.com/users', { statusCode: 201 })

stopAction

stopAction: (name: string, options?: ActionOptions) => void

Stop tracking a custom action started with startAction.

Sends a RUM action event with the elapsed duration since the matching start call. Context from start and stop calls is merged into the event.

Type Declaration

- (name: string, options?: ActionOptions): void
- Parameters
  - name: string
    Name of the action
  - Optionaloptions: ActionOptions
    Options of the action
  Returns void

stopResource

stopResource: (url: string, options?: ResourceStopOptions) => void

Stop tracking a resource started with startResource.

Sends a RUM resource event with the elapsed duration since the matching start call. Context from start and stop calls is merged into the event.

Type Declaration

- (url: string, options?: ResourceStopOptions): void
- Parameters
  - url: string
    URL of the resource
  - Optionaloptions: ResourceStopOptions
    Options of the resource
  Returns void

startView

startView(nameOrOptions?: string | ViewOptions): void
Start a view manually. Enable to manual start a view, use trackViewsManually: true init parameter and call startView() to create RUM views and be aligned with how you’ve defined them in your SPA application routing.

See Override default RUM view names for further information.

Context -
Parameters
- OptionalnameOrOptions: string | ViewOptions
  The view name, or a ViewOptions object to configure the view
Returns void
- Defined in packages/browser-rum-core/src/boot/rumPublicApi.ts:424

Session Replay

getSessionReplayLink

getSessionReplayLink: () => string | undefined

Get the Session Replay Link.

See Connect Session Replay To Your Third-Party Tools for further information.

startSessionReplayRecording

startSessionReplayRecording: (options?: StartRecordingOptions) => void

Start Session Replay recording. Enable to conditionally start the recording, use the startSessionReplayRecordingManually:true init parameter and call startSessionReplayRecording()

See Browser Session Replay for further information.

stopSessionReplayRecording

stopSessionReplayRecording: () => void

Stop Session Replay recording.

See Browser Session Replay for further information.

Context - Account

clearAccount

clearAccount: () => void

Clear all account information

Type Declaration

- (): void
- Returns void
  Clear all account information

getAccount

getAccount: () => Context

Get account information

Type Declaration

- (): Context
- Returns Context
  Account information

removeAccountProperty

removeAccountProperty: (key: string) => void

Remove an account property

Type Declaration

- (key: string): void
- Parameters
  - key: string
    Key of the property to remove
  Returns void

setAccount

setAccount: (newAccount: Account) => void

Set account information to all events, stored in @account

Type Declaration

- (newAccount: Account): void
- Parameters
  - newAccount: Account
    Account information
  Returns void

setAccountProperty

setAccountProperty: (key: string, property: any) => void

Set or update the account property, stored in @account.<key>

Type Declaration

- (key: string, property: any): void
- Parameters
  - key: string
    Key of the property
  - property: any
    Value of the property
  Returns void

Context - Global Context

getGlobalContext

getGlobalContext: () => Context

Get the global Context

See Global context for further information.

removeGlobalContextProperty

removeGlobalContextProperty: (key: any) => void

Remove a global context property

See Global context for further information.

setGlobalContext

setGlobalContext: (context: Context) => void

Set the global context information to all events, stored in @context See Global context for further information.

Type Declaration

- (context: Context): void
- Parameters
  - context: Context
    Global context
  Returns void

setGlobalContextProperty

setGlobalContextProperty: (key: any, value: any) => void

Set or update a global context property, stored in @context.<key>

See Global context for further information.

Type Declaration

- (key: any, value: any): void
- Parameters
  - key: any
    Key of the property
  - value: any
    Value of the property
  Returns void

clearGlobalContext

clearGlobalContext(): void
Clear the global context

See Global context for further information.

Returns void
- Defined in packages/browser-rum-core/src/boot/rumPublicApi.ts:314

Context - User

clearUser

clearUser: () => void

Clear all user information

See User session for further information.

getUser

getUser: () => Context

Get user information

See User session for further information.

Type Declaration

- (): Context
- Returns Context
  User information

removeUserProperty

removeUserProperty: (key: any) => void

Remove a user property

Type Declaration

- (key: any): void
- Parameters
  - key: any
    Key of the property to remove
  Returns void

See

User session for further information.

setUserProperty

setUserProperty: (key: any, property: any) => void

Set or update the user property, stored in @usr.<key>

See User session for further information.

Type Declaration

- (key: any, property: any): void
- Parameters
  - key: any
    Key of the property
  - property: any
    Value of the property
  Returns void

setUser

setUser(newUser: User & { id: string }): void
Set user information to all events, stored in @usr

See User session for further information.
Parameters
- newUser: User & { id: string }
  User information
Returns void
- Defined in packages/browser-rum-core/src/boot/rumPublicApi.ts:324
setUser(newUser: User): void
Set user information to all events, stored in @usr
Parameters
- newUser: User
  User information with optional id
Returns void
Deprecated
You must specify a user id, favor using setUser instead
- Defined in packages/browser-rum-core/src/boot/rumPublicApi.ts:333

Context - View

setViewContext

setViewContext: (context: Context) => void

Set View Context.

Enable to manually set the context of the current view.

Type Declaration

- (context: Context): void
- Parameters
  - context: Context
    Context of the view
  Returns void

setViewContextProperty

setViewContextProperty: (key: string, value: any) => void

Set View Context Property.

Enable to manually set a property of the context of the current view.

Type Declaration

- (key: string, value: any): void
- Parameters
  - key: string
    key of the property
  - value: any
    value of the property
  Returns void

setViewName

setViewName: (name: string) => void

Set View Name.

Enable to manually change the name of the current view. See Override default RUM view names for further information.

Type Declaration

- (name: string): void
- Parameters
  - name: string
    Name of the view
  Returns void

getViewContext

getViewContext(): Context
Get View Context.

Returns Context
- Defined in packages/browser-rum-core/src/boot/rumPublicApi.ts:145

Session

stopSession

stopSession(): void
Stop the session. A new session will start at the next user interaction with the page.

Returns void
- Defined in packages/browser-rum-core/src/boot/rumPublicApi.ts:431

Vital - Duration

addDurationVital

addDurationVital: (name: string, options: AddDurationVitalOptions) => void

Add a custom duration vital

Type Declaration

- (name: string, options: AddDurationVitalOptions): void
- Parameters
  - name: string
    Name of the custom vital
  - options: AddDurationVitalOptions
    Options for the custom vital (startTime, duration, context, description)
  Returns void

startDurationVital

startDurationVital: (name: string, options?: DurationVitalOptions) => void

Start a custom duration vital.

If you plan to have multiple durations for the same vital, use the vitalKey option to differentiate them. Provide the same key when calling stopDurationVital.

Type Declaration

- (name: string, options?: DurationVitalOptions): void
- Parameters
  - name: string
    Name of the custom vital
  - Optionaloptions: DurationVitalOptions
    Options for the custom vital (vitalKey, context, description)
  Returns void

Example

// Simple usage
datadogRum.startDurationVital('my-vital')
datadogRum.stopDurationVital('my-vital')

// Multiple simultaneous vitals with the same name
const key = crypto.randomUUID()
datadogRum.startDurationVital('my-vital', { vitalKey: key })
datadogRum.stopDurationVital('my-vital', { vitalKey: key })

stopDurationVital

stopDurationVital: (name: string, options?: DurationVitalOptions) => void

Stop a custom duration vital

Type Declaration

- (name: string, options?: DurationVitalOptions): void
- Parameters
  - name: string
    Name of the custom vital
  - Optionaloptions: DurationVitalOptions
    Options for the custom vital (vitalKey, context, description)
  Returns void

Vital - Feature Operation

failFeatureOperation

failFeatureOperation: (
    name: string,
    failureReason: FailureReason,
    options?: OperationOptions,
) => void

Mark a feature operation as failed.

Type Declaration

- (name: string, failureReason: FailureReason, options?: OperationOptions): void
- Parameters
  - name: string
    Name of the operation
  - failureReason: FailureReason
    Reason for the failure
  - Optionaloptions: OperationOptions
    Options for the operation (operationKey, context, description)
  Returns void

Deprecated

Use failOperation instead.

startFeatureOperation

startFeatureOperation: (name: string, options?: OperationOptions) => void

Start a feature operation.

Type Declaration

- (name: string, options?: OperationOptions): void
- Parameters
  - name: string
    Name of the operation
  - Optionaloptions: OperationOptions
    Options for the operation (operationKey, context, description)
  Returns void

Deprecated

Use startOperation instead.

succeedFeatureOperation

succeedFeatureOperation: (name: string, options?: OperationOptions) => void

Mark a feature operation as successful.

Type Declaration

- (name: string, options?: OperationOptions): void
- Parameters
  - name: string
    Name of the operation
  - Optionaloptions: OperationOptions
    Options for the operation (operationKey, context, description)
  Returns void

Deprecated

Use succeedOperation instead.

Vital - Operation

failOperation

failOperation: (
    name: string,
    failureReason: FailureReason,
    options?: OperationOptions,
) => void

Mark an operation as failed.

Sends a RUM vital event marking the end of the operation started with startOperation.

Type Declaration

- (name: string, failureReason: FailureReason, options?: OperationOptions): void
- Parameters
  - name: string
    Name of the operation
  - failureReason: FailureReason
    Reason for the failure
  - Optionaloptions: OperationOptions
    Options for the operation (operationKey, context, description)
  Returns void

startOperation

startOperation: (name: string, options?: OperationOptions) => void

Start an operation.

Call succeedOperation or failOperation with the same name (and optional operationKey) to send a RUM vital event marking the end of the operation.

Type Declaration

- (name: string, options?: OperationOptions): void
- Parameters
  - name: string
    Name of the operation
  - Optionaloptions: OperationOptions
    Options for the operation (operationKey, context, description)
  Returns void

Example

datadogRum.startOperation('checkout')
// ... perform the operation
datadogRum.succeedOperation('checkout')

succeedOperation

succeedOperation: (name: string, options?: OperationOptions) => void

Mark an operation as successful.

Sends a RUM vital event marking the end of the operation started with startOperation.

Type Declaration

- (name: string, options?: OperationOptions): void
- Parameters
  - name: string
    Name of the operation
  - Optionaloptions: OperationOptions
    Options for the operation (operationKey, context, description)
  Returns void

Other

DEFAULT_TRACKED_RESOURCE_HEADERS

DEFAULT_TRACKED_RESOURCE_HEADERS: readonly [
    "cache-control",
    "etag",
    "age",
    "expires",
    "content-type",
    "content-encoding",
    "vary",
    "content-length",
    "server-timing",
    "x-cache",
]

List of default headers used by the trackResourceHeaders option. See configuration example for extending them.

onReady

onReady: (callback: () => void) => void

For CDN async setup: Early RUM API calls must be wrapped in the window.DD_RUM.onReady() callback. This ensures the code only gets executed once the SDK is properly loaded.

See CDN async setup for further information.

version

version: string

Version of the Logs browser SDK

Interface DatadogRum

Hierarchy (View Summary)

Index

Init

Privacy

Data Collection

Session Replay

Context - Account

Context - Global Context

Context - User

Context - View

Session

Vital - Duration

Vital - Feature Operation

Vital - Operation

Other

Init

getInitConfiguration

Type Declaration

Returns RumInitConfiguration | undefined

init

Type Declaration

Parameters

Returns void

Example

Privacy

setTrackingConsent

Type Declaration

Parameters

Returns void

Data Collection

addAction

Type Declaration

Parameters

Returns void

addError

Type Declaration

Parameters

Returns void

addFeatureFlagEvaluation

Type Declaration

Parameters

Returns void

addTiming

Type Declaration

Parameters

Returns void

setViewLoadingTime

startAction

Type Declaration

Parameters

Returns void

Example

startResource

Type Declaration

Parameters

Returns void

Example

stopAction

Type Declaration

Parameters

Returns void

stopResource

Type Declaration

Parameters

Returns void

startView

Parameters

Returns void

Session Replay

getSessionReplayLink

startSessionReplayRecording

stopSessionReplayRecording

Context - Account

clearAccount

Type Declaration

Returns void

getAccount

Type Declaration

Returns Context