Skip to content

How to Configure RUM Session Sampling

RUM Session sampling controls the proportion of user sessions entering the data collection pipeline. Reducing the sampling rate can lower collection and storage costs.

Configure Session Sampling

sessionSampleRate ranges from 0 to 100:

  • 100: Collect all sessions.
  • 0: Do not collect regular sessions.
  • 1 to 99: Each new session is independently sampled according to the configured ratio.

For example, to collect 90% of Web RUM sessions:

import { datafluxRum } from "@truewatchtech/browser-rum"

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  service: "browser",
  env: "production",
  version: "1.0.0",
  sessionSampleRate: 90,
})

The above example uses a public OpenWay. When using DataKit direct connection, replace site and clientToken with datakitOrigin. Do not configure both report addresses simultaneously.

A session performs a random sampling once when it is created. The sampling result remains unchanged for the entire session lifecycle, and does not sample each View, Error, or Resource individually.

Session Replay uses its own independent sessionReplaySampleRate. Modifying sessionSampleRate does not automatically change the Session Replay sampling rate.

Start a New Session at Runtime

RUM SDK 3.3.6 introduced startSession(), supported by both the full RUM package and the slim RUM package.

Calling it immediately ends the current session and starts a new session based on the current sampling configuration, without waiting for the user's next click, scroll, or keyboard interaction:

datafluxRum.startSession()

When using CDN integration, use the same API:

window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSession()

Use cases include:

  • After user login, logout, or account switching, the two sessions before and after need to be isolated.
  • After the user agrees to privacy or monitoring policies, session sampling needs to be re-executed immediately.
  • During application runtime, the collection ratio for subsequent sessions needs to be adjusted.

Override Runtime Sampling Rate

You can pass a new sessionSampleRate when calling:

datafluxRum.startSession({
  sessionSampleRate: 100,
})

This value is used for:

  1. The session that is restarted this time.
  2. Subsequent sessions that are automatically renewed due to expiration, recovery, or user activity.

The sampling rate must be between 0 and 100. If an invalid value is passed, the SDK will output a configuration error and retain the current session without switching.

startSession() only switches the RUM session. It does not refresh the page, nor does it clear setUser(), Global Context, or other business states. When switching user accounts, update user information first, then start a new session.

Session ID and Sampling Result

startSession() re-executes session sampling. If the new session hits the sampling, a new session_id is generated. If it does not hit regular or error compensation sampling, no reportable regular RUM session is generated.

Relationship with Session Replay

startSession() only overrides sessionSampleRate. It does not override sessionReplaySampleRate or sessionReplayOnErrorSampleRate, nor does it automatically call startSessionReplayRecording().

When the application has already called startSessionReplayRecording(), whether the new session allows Replay upload is still determined by the new session sampling result and the existing Replay sampling configuration.

Sampling for Other Applications