Understanding RUM sampling: mechanism, rules, and best practices

​

What is sampling

import { flashcatRum } from "@flashcatcloud/browser-rum";

flashcatRum.init({
  applicationId: "<APPLICATION_ID>",
  clientToken: "<CLIENT_TOKEN>",
  sessionSampleRate: 20, // collect 20% of sessions
  sessionReplaySampleRate: 10, // of collected sessions, record session replay for 10%
});

​

How sampling works

​

1. The unit is the session, not the user or the event

​

2. The decision is sticky within a session

​

3. It is a probability, not an exact quota

​

4. The sampling rate is set when a session is drawn

​

Choosing a sampling rate

​

Best practice 1: adjust sampling dynamically with remote configuration

• Raise the session sample rate while a new version rolls out, then lower it back once it’s stable.
• Set it to 100 while you investigate a production issue, to capture as much evidence as possible.
• Lower it when data volume spikes, or set it to 0 to stop collection in an emergency.
• Lower the rate and turn on Capture additional sessions on error together, so sessions that weren’t drawn still report the lead-up when they hit an error. See best practice 3.

​

Enabling it and platform support

​

When changes take effect

• At the next new session: the SDK requests the configuration at startup and whenever a new session starts. A new configuration applies to the next draw, and running sessions keep their decision (rule 2). Clients usually switch within about 4 hours of a publish.
• Stored locally: the configuration is saved on the device, so the first session after the next launch (on the web, the next page load) is drawn with it right away. On the web, a page with nothing stored yet (such as a first visit or a private window) usually waits about 1 second for the configuration before collection starts, and the wait can be longer in a background tab. If the configuration does not arrive in time or the request fails, the first session uses the init() settings. Uncaught errors and console errors raised during the wait aren’t collected.
• Failures don’t change anything: if the request fails, times out, or returns something unreadable, the SDK keeps the configuration already in effect.

• The session sample rate is set to 0 (emergency stop), or raised from 0 to a non-zero value (resume).
• On the web, the replay privacy level becomes stricter.

​

Confirming the configuration is in effect

​

Best practice 2: business-defined custom sampling

{
  "incidentMode": false,
  "debugUsers": ["user_1024", "user_2048"],
  "salt": "2026q4"
}

flashcatRum.init({
  applicationId: "<APPLICATION_ID>",
  clientToken: "<CLIENT_TOKEN>",
  sessionSampleRate: 20, // Used until the console configuration arrives
  remoteConfigurationEnabled: true,
  beforeSampling: ({ sessionSampleRate, custom }) => {
    if (custom?.incidentMode) return { sessionSampleRate: 100 }; // Investigation mode: collect everything
    if (currentUser.isInternal || currentUser.isVip) return { sessionSampleRate: 100 }; // Key users: always collect
    if (custom?.debugUsers?.includes(currentUser.id)) return { sessionSampleRate: 100 }; // Investigation list: always collect

    // Base rule: deterministic hash bucketing by user ID; the bucket size follows the console's session sample rate
    const inBucket = hash(currentUser.id + (custom?.salt ?? "")) % 100 < sessionSampleRate;
    return { sessionSampleRate: inBucket ? 100 : 0 };
  },
});

val rumConfig = RumConfiguration.Builder(applicationId)
    .setSessionSampleRate(20f)            // Used until the console configuration arrives
    .setRemoteConfigurationEnabled(true)
    .setBeforeSampling { context ->
        val custom = context.custom
        val user = currentUser
        when {
            custom?.get("incidentMode") == true -> 100f            // Investigation mode: collect everything
            user.isInternal || user.isVip -> 100f                  // Key users: always collect
            (custom?.get("debugUsers") as? List<*>)?.contains(user.id) == true -> 100f // Investigation list: always collect
            // Base rule: deterministic hash bucketing by user ID; the bucket size follows the console's session sample rate
            else -> if (hash(user.id + (custom?.get("salt") ?: "")) % 100 < context.sessionSampleRate) 100f else 0f
        }
    }
    .build()
Rum.enable(rumConfig)

let rumConfig = RUM.Configuration(
    applicationID: "<RUM_APPLICATION_ID>",
    sessionSampleRate: 20,                // Used until the console configuration arrives
    remoteConfigurationEnabled: true,
    beforeSampling: { context in
        let custom = context.custom
        let user = currentUser
        if custom?["incidentMode"] as? Bool == true { return 100 }   // Investigation mode: collect everything
        if user.isInternal || user.isVip { return 100 }              // Key users: always collect
        if (custom?["debugUsers"] as? [String])?.contains(user.id) == true { return 100 } // Investigation list: always collect

        // Base rule: deterministic hash bucketing by user ID; the bucket size follows the console's session sample rate
        let salt = custom?["salt"] as? String ?? ""
        return Float(hash(user.id + salt) % 100) < context.sessionSampleRate ? 100 : 0
    }
)
RUM.enable(with: rumConfig)

flashcatRum.setForcedSession();

​

Why hash bucketing instead of random numbers

• User-level stability: the same user always gets the same decision, so you can answer “does user A have data?”. A sampled user has all sessions, and an unsampled user has none.
• Monotonic rollout: when the rate goes from 20% to 100%, every sampled user stays sampled and new users are only added. The data stays continuous and comparable. Changing the salt reshuffles all buckets.

​

Caveats

• Keep the callback light and deterministic. beforeSampling runs synchronously while a session is being created, so it must not make network requests or block, and the same input should give the same result. Drawing with Math.random() makes the same user’s decision flip back and forth; deterministic hashing avoids this by construction. If the callback returns a value outside 0–100 or throws, the SDK keeps the incoming rate.
• Rule changes take effect at the next new session. When a user moves from the “not sampled” bucket to the “sampled” one, the running session isn’t re-decided. To apply it right away, call setForcedSession() or stopSession().
• Custom configuration keys are public. They’re delivered to clients, and anyone holding the client token can read them. Never put secrets, access tokens, or personally sensitive information in them. Lists such as debugUsers should hold only user IDs that can’t be traced back to a person.
• Use sessionSampleRate: 0 instead of skipping init(). Skipping initialization breaks addAction / addError calls across your code and forces null checks everywhere. Passing 0 initializes a silent SDK and keeps one code path.
• Platform-side data reflects what was actually collected. With custom sampling, the platform can’t know your true sampling ratio. The session volume you see is what was collected, and you can’t extrapolate it to total traffic. If you need full-traffic estimates, compute them on your side based on your own sampling rules.

​

Best practice 3: full error capture with proportional sampling for the rest

• Error events: always kept — 100% of errors
• Failed requests: always kept — 100% of API failures (HTTP 5xx and request failures are resource events, not error events)
• Successful requests, user actions, long tasks: kept only for the winning 20% — the bulk of your volume converges to 20%

// Share of sessions that keep full data
const DETAIL_SAMPLE_RATE = 20;

// Map a bucket key stably onto 0-99 so every event with the same key lands in the same bucket
function bucketOf(key) {
  let hash = 0;
  for (let i = 0; i < key.length; i++) {
    hash = (hash * 31 + key.charCodeAt(i)) | 0;
  }
  return Math.abs(hash) % 100;
}

flashcatRum.init({
  applicationId: "<APPLICATION_ID>",
  clientToken: "<CLIENT_TOKEN>",
  sessionSampleRate: 100, // Collect every session so no error is dropped
  trackResources: true,
  trackUserInteractions: true,
  trackLongTasks: true,
  beforeSend: (event) => {
    const isDetail = bucketOf(event.session.id) < DETAIL_SAMPLE_RATE;

    // Stamp every surviving event so the session declares whether it is a full
    // picture or an errors-only summary
    event.context = {
      ...event.context,
      rum_sampling: isDetail ? "full" : "errors_only",
    };

    // View events cannot be dismissed; let them through explicitly to avoid an SDK warning
    if (event.type === "view") return true;

    // Always keep error events
    if (event.type === "error") return true;

    // Always keep failed requests
    if (event.type === "resource") {
      const statusCode = event.resource.status_code;
      if (statusCode === 0 || statusCode >= 400) return true;
    }

    // Everything else is kept only for sessions that win the draw
    return isDetail;
  },
});

const REPLAY_SAMPLE_RATE = 10; // share of detail sessions that get recorded

flashcatRum.init({
  sessionSampleRate: 100,
  sessionReplaySampleRate: 0, // turn the automatic draw off entirely
  startSessionReplayRecordingManually: true,
  // ...
});

const context = flashcatRum.getInternalContext();
if (context) {
  const sessionId = context.session_id;
  const inDetailBucket = bucketOf(sessionId) < DETAIL_SAMPLE_RATE;
  // Salt the key to get a second draw uncorrelated with the detail bucket
  const inReplayBucket = bucketOf(`replay:${sessionId}`) < REPLAY_SAMPLE_RATE;

  if (inDetailBucket && inReplayBucket) {
    // force lets a session that lost the replay draw start recording anyway
    flashcatRum.startSessionReplayRecording({ force: true });
  }
}

// Share of users that keep full data
const DETAIL_SAMPLE_RATE = 20;
// Share of detail users that get recorded
const REPLAY_SAMPLE_RATE = 10;

// Map a bucket key stably onto 0-99 so every event with the same key lands in the same bucket
function bucketOf(key) {
  let hash = 0;
  for (let i = 0; i < key.length; i++) {
    hash = (hash * 31 + key.charCodeAt(i)) | 0;
  }
  return Math.abs(hash) % 100;
}

// Implemented by your code: signed-in user ID first, otherwise your own
// anonymous ID (generated once and stored in localStorage)
const bucketKey = getCurrentUserId() || getOrCreateAnonId();
const inDetailBucket = bucketOf(bucketKey) < DETAIL_SAMPLE_RATE;

flashcatRum.init({
  applicationId: "<APPLICATION_ID>",
  clientToken: "<CLIENT_TOKEN>",
  sessionSampleRate: 100, // Collect every session so no error is dropped
  // Replay alignment: draw REPLAY_SAMPLE_RATE within detail users, never
  // record the rest (omit this line if you do not use Session Replay)
  sessionReplaySampleRate: inDetailBucket ? REPLAY_SAMPLE_RATE : 0,
  trackResources: true,
  trackUserInteractions: true,
  trackLongTasks: true,
  beforeSend: (event) => {
    // The exact same decision as before init(), so the two cannot drift
    const isDetail = bucketOf(getCurrentUserId() || getOrCreateAnonId()) < DETAIL_SAMPLE_RATE;

    // Stamp every surviving event so the session declares whether it is a full
    // picture or an errors-only summary
    event.context = {
      ...event.context,
      rum_sampling: isDetail ? "full" : "errors_only",
    };

    // View events cannot be dismissed; let them through explicitly to avoid an SDK warning
    if (event.type === "view") return true;

    // Always keep error events
    if (event.type === "error") return true;

    // Always keep failed requests
    if (event.type === "resource") {
      const statusCode = event.resource.status_code;
      if (statusCode === 0 || statusCode >= 400) return true;
    }

    // Everything else is kept only for users that win the draw
    return isDetail;
  },
});

​

Three things to know before adopting this

• Volume will not land exactly on 20%. View events are the skeleton of a session and cannot be dismissed, so they still report at 100%. How far volume actually falls depends on the share of resource and action events in your data.
• Absolute counts need to be scaled. The platform still shows 100% of sessions, but only about 20% carry full data. Ratios and percentiles such as error rate and P75 are unaffected, because a random sample still represents the whole. Scale absolute counts, such as total resource requests or clicks, by 1 / 20%.
• Session Replay needs one explicit alignment step. This recipe sets sessionSampleRate to 100, so the SDK assumes every session is collected in full and draws replay across all of them. Skip the alignment step in the matching tab above and replay lands on sessions outside the bucket — you get the recording, but the session behind it holds no behavior data.

​

Platform support

​

FAQ

flashcatRum.init({
  applicationId: "<APPLICATION_ID>",
  clientToken: "<CLIENT_TOKEN>",
  sessionSampleRate: 100, // Collect every session so no error is missed
  trackResources: true, // Must stay on, otherwise API failures are invisible
  trackLongTasks: false,
  trackUserInteractions: false,
  trackWebVitals: false,
  beforeSend: (event) => {
    // Keep only failed requests; successful ones are discarded and cost nothing
    if (event.type === "resource") {
      const statusCode = event.resource.status_code;
      return statusCode === 0 || statusCode >= 400;
    }
    return true;
  },
});