RumMonitor

interface RumMonitor

A class enabling Datadog RUM features.

It allows you to record User events that can be explored and analyzed in Datadog Dashboards.

You can only have one active RumMonitor, and should retrieve it from the GlobalRumMonitor object.

Properties

debug

abstract var debug: Boolean

Utility setting to inspect the active RUM View. If set, a debugging outline will be displayed on top of the application, describing the name of the active RUM View in the default SDK instance (if any). May be used to debug issues with RUM instrumentation in your app.

Default value is false.

Functions

_getInternal

abstract fun _getInternal(): _RumInternalProxy?

For Datadog internal use only.

See also

_RumInternalProxy

addAction

abstract fun addAction(type: RumActionType, name: String, attributes: Map<String, Any?>)

Notifies that an action happened. This is used to track discrete actions (e.g.: tap).

Parameters

type	the action type
name	the action identifier
attributes	additional custom attributes to attach to the action. Attributes can be nested up to 9 levels deep. Keys using more than 9 levels will be sanitized by SDK.

See also

RumMonitor.startAction
RumMonitor.stopAction

addAttribute

abstract fun addAttribute(key: String, value: Any?)

Adds a global attribute to all future RUM events.

Parameters

key	the attribute key (non null)
value	the attribute value (or null)

addError

abstract fun addError(message: String, source: RumErrorSource, throwable: Throwable?, attributes: Map<String, Any?>)

Notifies that an error occurred in the active View.

Parameters

message	a message explaining the error
source	the source of the error
throwable	the throwable
attributes	additional custom attributes to attach to the error. Attributes can be nested up to 9 levels deep. Keys using more than 9 levels will be sanitized by SDK. Users that want to supply a custom fingerprint for this error can add a value under the key RumAttributes.ERROR_FINGERPRINT

addErrorWithStacktrace

abstract fun addErrorWithStacktrace(message: String, source: RumErrorSource, stacktrace: String?, attributes: Map<String, Any?>)

Notifies that an error occurred in the active View.

This method is meant for non-native or cross platform frameworks (such as React Native or Flutter) to send error information to Datadog. Although it can be used directly, it is recommended to pass a Throwable instead.

Parameters

message	a message explaining the error
source	the source of the error
stacktrace	the error stacktrace information
attributes	additional custom attributes to attach to the error. Users that want to supply a custom fingerprint for this error can add a value under the key RumAttributes.ERROR_FINGERPRINT

addFeatureFlagEvaluation

abstract fun addFeatureFlagEvaluation(name: String, value: Any)

Adds result of evaluating a feature flag to the view. Feature flag evaluations are local to the active view and are cleared when the view is stopped. If you need to submit more than one feature flag evaluation at the same time, consider using the addFeatureFlagEvaluations method instead.

Parameters

name	the name of the feature flag
value	the value the feature flag evaluated to

addFeatureFlagEvaluations

abstract fun addFeatureFlagEvaluations(featureFlags: Map<String, Any>)

Adds result of evaluating a set of feature flag to the view. Feature flag evaluations are local to the active view and are cleared when the view is stopped.

Parameters

featureFlags	the map of feature flags

addTiming

abstract fun addTiming(name: String)

Adds a specific timing in the active View. The timing duration will be computed as the difference between the time the View was started and the time this function was called.

Parameters

name	the name of the new custom timing attribute. Timings can be nested up to 8 levels deep. Names using more than 8 levels will be sanitized by SDK.

clearAttributes

abstract fun clearAttributes()

Clear all the global attributes added to this monitor.

getAttributes

abstract fun getAttributes(): Map<String, Any?>

Return

the global attributes added to this monitor

getCurrentSessionId

abstract fun getCurrentSessionId(callback: (String?) -> Unit)

Get the current active session ID. The session ID will be null if no session is active or if the session has been sampled out.

This method uses an asynchronous callback to ensure all pending RUM events have been processed up to the moment of the call.

Parameters

callback	the callback to be invoked with the current session id.

removeAttribute

abstract fun removeAttribute(key: String)

Removes a global attribute from all future RUM events.

Parameters

key	the attribute key (non null)

startAction

abstract fun startAction(type: RumActionType, name: String, attributes: Map<String, Any?>)

Notifies that an action started. This is used to track long running actions (e.g.: scroll). Such an action must be stopped with stopAction, and will be stopped automatically if it lasts more than 10 seconds.

Parameters

type	the action type
name	the action identifier
attributes	additional custom attributes to attach to the action. Attributes can be nested up to 9 levels deep. Keys using more than 9 levels will be sanitized by SDK.

See also

RumMonitor.stopAction
RumMonitor.addAction

startResource

abstract fun startResource(key: String, method: RumResourceMethod, url: String, attributes: Map<String, Any?> = emptyMap())

Notify that a new Resource is being loaded, linked with the key instance.

Parameters

key	the instance that represents the resource being loaded (usually your request or network call instance).
method	the method used to load the resource (E.g., for network: "GET" or "POST")
url	the url or local path of the resource being loaded
attributes	additional custom attributes to attach to the resource. Attributes can be nested up to 9 levels deep. Keys using more than 9 levels will be sanitized by SDK.

See also

RumMonitor.stopResource
RumMonitor.stopResourceWithError

abstract fun startResource(key: String, method: String, url: String, attributes: Map<String, Any?> = emptyMap())

---

Deprecated

This method is deprecated and will be removed in the future versions. Use startResource method which takes RumHttpMethod as method parameter instead.

---

Notify that a new Resource is being loaded, linked with the key instance.

Parameters

key	the instance that represents the resource being loaded (usually your request or network call instance).
method	the method used to load the resource (E.g., for network: "GET" or "POST")
url	the url or local path of the resource being loaded
attributes	additional custom attributes to attach to the resource. Attributes can be nested up to 9 levels deep. Keys using more than 9 levels will be sanitized by SDK.

See also

RumMonitor.stopResource
RumMonitor.stopResourceWithError

startView

abstract fun startView(key: Any, name: String, attributes: Map<String, Any?> = emptyMap())

Notifies that a View is being shown to the user, linked with the key instance.

Parameters

key	the instance that represents the active view (usually your Activity or Fragment instance).
name	the name of the view (usually your Activity or Fragment full class name)
attributes	additional custom attributes to attach to the view. Attributes can be nested up to 9 levels deep. Keys using more than 9 levels will be sanitized by SDK.

See also

RumMonitor.stopView

stopAction

abstract fun stopAction(type: RumActionType, name: String, attributes: Map<String, Any?> = emptyMap())

Notifies that an action stopped, and update the action's type and name. This is used to stop tracking long running actions (e.g.: scroll), started with startAction.

Parameters

type	the action type (overriding the last started action)
name	the action identifier (overriding the last started action)
attributes	additional custom attributes to attach to the action. Attributes can be nested up to 9 levels deep. Keys using more than 9 levels will be sanitized by SDK.

See also

RumMonitor.addAction
RumMonitor.startAction

stopResource

abstract fun stopResource(key: String, statusCode: Int?, size: Long?, kind: RumResourceKind, attributes: Map<String, Any?>)

Stops a previously started Resource, linked with the key instance.

Parameters

key	the instance that represents the active view (usually your request or network call instance).
statusCode	the status code of the resource (if any)
size	the size of the resource, in bytes
kind	the type of resource loaded
attributes	additional custom attributes to attach to the resource. Attributes can be nested up to 9 levels deep. Keys using more than 9 levels will be sanitized by SDK.

See also

RumMonitor.startResource
RumMonitor.stopResourceWithError

stopResourceWithError

abstract fun stopResourceWithError(key: String, statusCode: Int?, message: String, source: RumErrorSource, throwable: Throwable, attributes: Map<String, Any?> = emptyMap())

Stops a previously started Resource that failed loading, linked with the key instance.

Parameters

key	the instance that represents the active view (usually your request or network call instance).
statusCode	the status code of the resource (if any)
message	a message explaining the error
source	the source of the error
throwable	the throwable
attributes	additional custom attributes to attach to the error. Attributes can be nested up to 9 levels deep. Keys using more than 9 levels will be sanitized by SDK. Users that want to supply a custom fingerprint for this error can add a value under the key RumAttributes.ERROR_FINGERPRINT

See also

RumMonitor.startResource
RumMonitor.stopResource

abstract fun stopResourceWithError(key: String, statusCode: Int?, message: String, source: RumErrorSource, stackTrace: String, errorType: String?, attributes: Map<String, Any?> = emptyMap())

Stops a previously started Resource that failed loading, linked with the key instance by providing the intercepted stacktrace. Note: This method should only be used from hybrid application.

Parameters

key	the instance that represents the active view (usually your request or network call instance).
statusCode	the status code of the resource (if any)
message	a message explaining the error
source	the source of the error
stackTrace	the error stacktrace
errorType	the type of the error. Usually it should be the canonical name of the of the Exception class.
attributes	additional custom attributes to attach to the error. Attributes can be nested up to 9 levels deep. Keys using more than 9 levels will be sanitized by SDK. Users that want to supply a custom fingerprint for this error can add a value under the key RumAttributes.ERROR_FINGERPRINT

See also

RumMonitor.startResource
RumMonitor.stopResource

stopSession

abstract fun stopSession()

Stops the current session. A new session will start in response to a call to startView, addAction, or startAction. If the session is started because of a call to addAction, or startAction, the last know view is restarted in the new session.

stopView

abstract fun stopView(key: Any, attributes: Map<String, Any?> = emptyMap())

Stops a previously started View, linked with the key instance.

Parameters

key	the instance that represents the active view (usually your Activity or Fragment instance).
attributes	additional custom attributes to attach to the view. Attributes can be nested up to 9 levels deep. Keys using more than 9 levels will be sanitized by SDK.

See also

RumMonitor.startView