理解 RUM 采样：机制、规则与最佳实践

采样决定了有多少真实用户数据会被采集上报。采样率设置过高会带来不必要的数据量与费用，设置过低则可能漏掉关键问题。本文介绍 RUM 采样的工作机制，并给出选择和动态管理采样率的最佳实践。

采样是什么

RUM SDK 通过 sessionSampleRate 参数控制采样，取值 0 到 100，表示被采集的会话百分比：

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

flashcatRum.init({
  applicationId: "<APPLICATION_ID>",
  clientToken: "<CLIENT_TOKEN>",
  sessionSampleRate: 20, // 采集 20% 的会话
  sessionReplaySampleRate: 10, // 已采集会话中，再抽 10% 录制会话重放
});

被采样命中的会话会上报全部数据（页面浏览、资源、错误、用户行为等）；未命中的会话不上报任何数据——包括错误。这是理解采样的第一个关键点：采样率 20% 意味着线上 80% 的用户出了错，您在平台上是看不到的。 sessionReplaySampleRate 是在已采集会话基础上的二次抽样：sessionSampleRate: 20 且 sessionReplaySampleRate: 10 时，实际有会话重放录制的会话占全部流量的 2%。

采样的工作规则

理解以下四条规则，可以避免绝大多数「为什么配了采样率但行为不符合预期」的困惑。

1. 以会话为单位，而不是用户或事件

采样判定发生在会话开始时：SDK 按 sessionSampleRate 的概率抛一次硬币，中签则整个会话完整上报，不中签则整个会话完全静默。不存在「一个会话里 20% 的事件被上报」这种情况——会话数据要么完整，要么没有。同一个用户今天的会话可能中签、明天的会话可能不中签。默认的采样机制不锚定具体用户。

2. 判定结果在会话内粘滞

抽签结果会随会话状态持久化（Web 端存储在 Cookie 中）。会话在用户持续活跃时最长保持 4 小时，不活跃 15 分钟后过期；期间用户刷新页面、跳转页面都不会重新抽签。只有会话过期后产生新会话时，才会按当时的采样率重新判定。

这意味着修改采样率后，新会话立即按新采样率判定，存量会话维持原判定直到自然过期。这正是渐进放量的正确语义，但也意味着调整不是瞬时全量生效的。

3. 是概率，不是精确配额

每个会话的抽签相互独立，没有全局协调。采样率 20% 表示期望值是 20%：流量越大，实际采集比例越接近 20%（大数定律）；流量较小时会有明显波动，100 个会话实际采到 13 个或 28 个都是正常的。

4. 采样率在初始化时固化

sessionSampleRate 在 init() 调用时确定，初始化后无法在运行时修改，页面生命周期内也不能二次 init()。想改变采样率，需要让下一次初始化（Web 端即下一次页面加载）拿到新的值——下文的动态调整方案正是围绕这一点展开。

如何选择采样率

场景	建议
测试 / 预发环境	`sessionSampleRate: 100`，流量小，全量采集便于验证
生产环境（中小流量）	50–100，优先保证问题可见性
生产环境（大流量）	10–30，结合数据量与费用权衡
会话重放	通常 1–10，重放是 SDK 开销与数据量的主要来源
新版本发布期	临时调高（如 100），稳定后降回常规值
线上故障排查期	临时调至 100，尽可能多地捕捉现场

错误是低频事件。如果您的核心诉求是错误监控而非性能统计，宁可选择更高的采样率——性能指标 20% 的样本足够代表整体，而某个只影响 1% 用户的错误在 20% 采样下可能很久才出现一次。

最佳实践一：让采样率可以动态调整

采样率写死在代码里，意味着每次调整都要发版。推荐把采样率外置到您自己的配置中心，SDK 初始化时读取：

Web
Android
iOS

const CACHE_KEY = "rum-sample-rate";

// 1. 用本地缓存的值立即初始化，不阻塞 SDK 启动
const cached = Number(localStorage.getItem(CACHE_KEY));
const sampleRate = Number.isFinite(cached) && cached > 0 ? cached : 20;

flashcatRum.init({
  // ...其他配置
  sessionSampleRate: sampleRate,
});

// 2. 异步拉取最新值，供下一次页面加载使用
fetch("https://your-config-server.example.com/rum-config")
  .then((res) => res.json())
  .then(({ sessionSampleRate: latest }) => {
    localStorage.setItem(CACHE_KEY, String(latest));
    // 3. 采样率变化时结束当前会话，让新判定尽快生效
    if (latest !== sampleRate) {
      flashcatRum.stopSession();
    }
  })
  .catch(() => {}); // 拉取失败时沿用缓存值，不影响采集

val prefs = getSharedPreferences("rum_config", Context.MODE_PRIVATE)

// 1. 用本地缓存的值立即初始化，不阻塞 SDK 启动
val sampleRate = prefs.getFloat("session_sample_rate", 20f)

val rumConfig = RumConfiguration.Builder(applicationId)
    .setSessionSampleRate(sampleRate)
    .build()
Rum.enable(rumConfig)

// 2. 异步拉取最新值写入缓存，下次冷启动生效
CoroutineScope(Dispatchers.IO).launch {
    runCatching { fetchRumConfig() } // 请求您自己的配置服务
        .onSuccess { config ->
            prefs.edit()
                .putFloat("session_sample_rate", config.sessionSampleRate)
                .apply()
        } // 拉取失败时沿用缓存值，不影响采集
}

let defaults = UserDefaults.standard

// 1. 用本地缓存的值立即初始化，不阻塞 SDK 启动
let sampleRate = defaults.object(forKey: "rumSessionSampleRate") as? Float ?? 20

var rumConfig = RUM.Configuration(applicationID: "<RUM_APPLICATION_ID>")
rumConfig.sessionSampleRate = sampleRate
RUM.enable(with: rumConfig)

// 2. 异步拉取最新值写入缓存，下次冷启动生效
URLSession.shared.dataTask(with: configURL) { data, _, _ in
    guard let data,
          let config = try? JSONDecoder().decode(RumRemoteConfig.self, from: data)
    else { return } // 拉取失败时沿用缓存值，不影响采集
    defaults.set(config.sessionSampleRate, forKey: "rumSessionSampleRate")
}.resume()

三个要点：

不要为等配置阻塞初始化。同步等待配置接口会漏掉页面早期的数据，配置服务抖动还会拖垮 RUM 启动。正确姿势是「缓存值立即初始化 + 异步刷新缓存供下次使用」，新采样率晚一个页面周期生效完全可以接受。
采样率变化时调用 stopSession()（仅 Web / 小程序）。由于判定结果在会话内粘滞（规则 2），一个在 20% 时代未中签的用户，即使新页面以 100% 初始化，也会因为存量会话的旧判定而继续静默，最长持续 4 小时。stopSession() 会让当前会话立即过期，用户的下一次交互产生新会话并按新采样率重新抽签。注意这招在移动端无效：移动端采样率在初始化时就冻结在采样器里，stopSession() 之后的新会话仍按旧值抽签，新值默认要等下次冷启动重新初始化才生效。如需立即生效，参见下方移动端进阶方案。
拉取失败必须有兜底。配置接口不可用时沿用缓存值或内置默认值，保证采集不中断。

stopSession() 会把一个用户的连续行为切分成两个会话，导致会话数轻微膨胀、会话时长统计断开。只在采样率确实变化时调用它，不要每次页面加载都调用。

移动端进阶：让新采样率立即生效

移动端 App 进程可能存活数天，“下次冷启动生效”在事故排查这类需要立即全量采集的场景下不够用。此时可以走完整重建路径：stopInstance() 停止当前 SDK 实例，再用新采样率重新初始化。要点是拉到新配置时只记录、不立刻重建，等 App 回前台这类安静的生命周期点再执行——在用户操作中途重建会切断当前视图和会话上下文。

Android
iOS

// 拉取到新配置时只记录待生效值，不立刻重建
fun onConfigFetched(latest: RumRemoteConfig) {
    prefs.edit().putFloat("session_sample_rate", latest.sessionSampleRate).apply()
    pendingSampleRate = latest.sessionSampleRate.takeIf { it != currentSampleRate }
}

// App 回前台这类安静时机再执行重建
ProcessLifecycleOwner.get().lifecycle.addObserver(object : DefaultLifecycleObserver {
    override fun onStart(owner: LifecycleOwner) {
        val newRate = pendingSampleRate ?: return
        pendingSampleRate = null

        Datadog.stopInstance() // 停止当前实例
        Datadog.initialize(context, coreConfiguration, TrackingConsent.GRANTED)
        val rumConfig = RumConfiguration.Builder(applicationId)
            .setSessionSampleRate(newRate)
            .build()
        Rum.enable(rumConfig) // 启用过的其他产品（Logs、Trace 等）也要一并重新 enable
        currentSampleRate = newRate
    }
})

// 拉取到新配置时只记录待生效值，不立刻重建
func onConfigFetched(_ latest: RumRemoteConfig) {
    defaults.set(latest.sessionSampleRate, forKey: "rumSessionSampleRate")
    pendingSampleRate = latest.sessionSampleRate != currentSampleRate
        ? latest.sessionSampleRate : nil
}

// App 回前台这类安静时机再执行重建
NotificationCenter.default.addObserver(
    forName: UIApplication.willEnterForegroundNotification, object: nil, queue: .main
) { _ in
    guard let newRate = pendingSampleRate else { return }
    pendingSampleRate = nil

    Datadog.stopInstance() // 停止当前实例
    Datadog.initialize(with: coreConfiguration, trackingConsent: .granted)
    var rumConfig = RUM.Configuration(applicationID: "<RUM_APPLICATION_ID>")
    rumConfig.sessionSampleRate = newRate
    RUM.enable(with: rumConfig) // 启用过的其他产品（Logs、Trace 等）也要一并重新 enable
    currentSampleRate = newRate
}

重建是有代价的进阶操作，上线前请确认以下风险：

时机敏感：在用户操作中途重建会切断当前视图/会话上下文，把连续行为切成两段会话。务必挑安静的生命周期点执行（如上例的 App 回前台时），而不是配置一到就立刻重建。
数据丢失风险：stopInstance() 时本地缓冲区中尚未上传的数据是否会被完整发送，需要在您的环境中实测验证。
重建负担：同一实例上启用过的所有产品（RUM、Logs、Trace、Session Replay）以及视图追踪策略、网络拦截器都要重新注册，漏掉任何一块就是静默的采集降级。
适用边界：建议仅用于”事故排查需要立即全量”这类场景；常规的采样率调整走”下次冷启动生效”即可，零风险。React Native 未暴露 stopInstance，只能下次启动生效。

最佳实践二：业务自定义采样

默认的随机抽签对所有用户一视同仁，但业务往往希望差异化：VIP 用户全量采集、灰度用户重点观察、出过错的用户下次必采。这时可以把抽签逻辑从 SDK 挪到业务代码：业务自行判定当前会话是否采样，SDK 的 sessionSampleRate 只传 0 或 100，退化为开关。

Web
Android
iOS

function decideSampling(user, config) {
  // 优先级从高到低的短路规则
  if (config.incidentMode) return true;           // 故障排查模式：全量采集
  if (user.isInternal || user.isBeta) return true; // 内部/灰度用户：必采
  if (user.isVip) return true;                     // 重点用户：必采
  if (localStorage.getItem("rum-had-error")) return true; // 上次出过错：必采

  // 底座：按 userId 确定性哈希分桶
  return hash(user.id + config.salt) % 100 < config.sampleRate;
}

const sampled = decideSampling(currentUser, cachedConfig);

flashcatRum.init({
  // ...其他配置
  sessionSampleRate: sampled ? 100 : 0,
});

fun decideSampling(user: User, config: RumRemoteConfig): Boolean {
    // 优先级从高到低的短路规则
    if (config.incidentMode) return true            // 故障排查模式：全量采集
    if (user.isInternal || user.isBeta) return true // 内部/灰度用户：必采
    if (user.isVip) return true                     // 重点用户：必采
    if (prefs.getBoolean("rum_had_error", false)) return true // 上次出过错：必采

    // 底座：按 userId 确定性哈希分桶
    return hash(user.id + config.salt) % 100 < config.sampleRate
}

val sampled = decideSampling(currentUser, cachedConfig)

val rumConfig = RumConfiguration.Builder(applicationId)
    .setSessionSampleRate(if (sampled) 100f else 0f)
    .build()
Rum.enable(rumConfig)

func decideSampling(user: User, config: RumRemoteConfig) -> Bool {
    // 优先级从高到低的短路规则
    if config.incidentMode { return true }            // 故障排查模式：全量采集
    if user.isInternal || user.isBeta { return true } // 内部/灰度用户：必采
    if user.isVip { return true }                     // 重点用户：必采
    if UserDefaults.standard.bool(forKey: "rumHadError") { return true } // 上次出过错：必采

    // 底座：按 userId 确定性哈希分桶
    return hash(user.id + config.salt) % 100 < config.sampleRate
}

let sampled = decideSampling(user: currentUser, config: cachedConfig)

var rumConfig = RUM.Configuration(applicationID: "<RUM_APPLICATION_ID>")
rumConfig.sessionSampleRate = sampled ? 100 : 0
RUM.enable(with: rumConfig)

为什么用哈希分桶代替随机数

底座规则用 hash(userId) % 100 而不是 Math.random()，带来两个默认抽签没有的性质：

用户级稳定：同一个用户的判定结果永远一致，您可以回答「用户 A 有没有数据」——中签用户的所有会话都在，未中签用户则明确没有。
放量单调：采样率从 20% 调到 100% 时，原本中签的用户全部继续中签，新增的是纯增量，前后数据连续可对比。换一个 salt 即可整体重新洗牌。

注意事项

判定必须在会话内稳定。如果用 Math.random() 每次页面加载现抽，同一会话内不同页面可能得出不同结果，而 SDK 只认会话首次判定——表现为「配了 100 却不上报」，非常难排查。确定性哈希天然规避这个问题。
规则变化时同样需要切换会话。用户从「不采」桶进入「采」桶时，参照最佳实践一的做法：Web / 小程序在检测到本次判定与上次缓存的判定不同时调用一次 stopSession()；移动端默认下次冷启动生效，或参照进阶方案重建实例。
用 sessionSampleRate: 0 而不是跳过 init()。跳过初始化会让业务代码里的 addAction / addError 等调用失效，到处判空很繁琐；传 0 让 SDK 正常初始化为静默状态，代码路径统一。
平台侧数据代表实际采集量。自定义采样时，平台无法感知您的真实采样比例，看到的会话量即实际采集量，无法按采样率反推全量流量。如需估算全量，请在业务侧基于自己的采样规则换算。

最佳实践三：错误全量采集，其余数据按比例保留

一个常见的诉求是「把数据量降到 20%，但异常一条都不能漏」。直接把 sessionSampleRate 设成 20 做不到：采样以会话为单位，未命中的会话连错误也不上报（规则 1），异常会同步丢掉八成。正确做法是会话全量采集保证错误不漏，再在 beforeSend 里按稳定 key 分桶，只让中签的那部分保留完整数据：

错误事件：全部保留，异常 100%
失败的请求：全部保留，接口报错 100%（HTTP 5xx 与请求失败是资源事件，不是错误事件）
成功的请求、用户行为、长任务：只保留中签的 20%，数据量的大头按 20% 收敛

分桶方式二选一，下面两个 Tab 各自是完整可抄的方案，先对照下表选定一种：

	按会话分桶	按用户分桶
前置依赖	无，开箱即用	业务侧自己持有 key（登录用户 ID 或自维护的匿名 ID）
数据代表性	每条会话重新抽签，长期更能代表整体人群	样本固定，同一批用户的设备、网络与地域特征会固化进指标
体验一致性	同一用户的不同会话可能落进不同桶	同一用户始终一致；放量单调——20% 提到 100% 时原有人群保留，前后数据可比
重放对齐	手动录制（约 10 行代码）	`init()` 时一行配置，但要求 key 在初始化前可得

另外，如果接入了会话重放，还需要一步对齐：原生语义下重放是已采集会话之上的二次抽样，而本方案把 sessionSampleRate 设成了 100，SDK 会以为每条会话都被完整采集，从而在全部会话上抽回放——其中一部分落在细节分桶之外，表现为「有回放，却没有行为数据」。两个 Tab 里各自给出了对应的对齐做法，不用重放可以跳过。

按会话分桶
按用户分桶

数据采样的完整配置：

// 保留完整数据的会话占比
const DETAIL_SAMPLE_RATE = 20;

// 把分桶 key 稳定映射到 0-99，同一个 key 的所有事件落在同一个桶
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, // 会话全量采集，保证错误一条不漏
  trackResources: true,
  trackUserInteractions: true,
  trackLongTasks: true,
  beforeSend: (event) => {
    const isDetail = bucketOf(event.session.id) < DETAIL_SAMPLE_RATE;

    // 给每条留下来的事件盖章，标明这条会话是完整现场还是仅错误摘要
    event.context = {
      ...event.context,
      rum_sampling: isDetail ? "full" : "errors_only",
    };

    // 视图事件无法丢弃，显式放行以免触发 SDK 告警
    if (event.type === "view") return true;

    // 错误事件永远保留
    if (event.type === "error") return true;

    // 失败的请求永远保留
    if (event.type === "resource") {
      const statusCode = event.resource.status_code;
      if (statusCode === 0 || statusCode >= 400) return true;
    }

    // 其余数据只保留中签会话的
    return isDetail;
  },
});

重放对齐：会话 ID 在 init() 之前还不存在，而重放采样率在初始化时就固化了，所以要关掉自动抽签、改用手动录制，初始化完成后自行做第二层抽样。把下面两个选项并入上面的 init()，并在 init() 之后执行一次判定：

const REPLAY_SAMPLE_RATE = 10; // 细节会话中再录制多少比例

flashcatRum.init({
  sessionSampleRate: 100,
  sessionReplaySampleRate: 0, // 关掉自动抽签，完全交给下面判定
  startSessionReplayRecordingManually: true,
  // ...
});

const context = flashcatRum.getInternalContext();
if (context) {
  const sessionId = context.session_id;
  const inDetailBucket = bucketOf(sessionId) < DETAIL_SAMPLE_RATE;
  // 加盐得到一个与细节分桶不相关的第二次抽签
  const inReplayBucket = bucketOf(`replay:${sessionId}`) < REPLAY_SAMPLE_RATE;

  if (inDetailBucket && inReplayBucket) {
    // force 让未中签重放的会话也能开始录制
    flashcatRum.startSessionReplayRecording({ force: true });
  }
}

手动录制方案有一个已知边界：会话在页面存活期间过期续期后（不活跃 15 分钟或持续 4 小时），新会话是新的 ID、落进新的桶，需要重新判定一次，而 SDK 没有暴露会话续期事件。长时间停留的页面若要严格对齐，需自行轮询 getInternalContext().session_id 的变化。

分桶 key 必须来自 init() 之前就可得的来源：登录用户 ID，或业务自维护的匿名 ID（自己生成并存入 localStorage）。SDK 虽会把跨会话匿名 ID 回填到 event.usr.id（trackAnonymousUser 默认开启），但它要等初始化才生成，赶不上初始化时的重放判定——所以 init() 和 beforeSend 统一使用业务侧的 key，一份配置到底：

// 保留完整数据的用户占比
const DETAIL_SAMPLE_RATE = 20;
// 细节用户中再录制多少比例的回放
const REPLAY_SAMPLE_RATE = 10;

// 把分桶 key 稳定映射到 0-99，同一个 key 的所有事件落在同一个桶
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;
}

// 业务自行实现：登录用户 ID 优先，否则用自维护的匿名 ID（生成后存入 localStorage）
const bucketKey = getCurrentUserId() || getOrCreateAnonId();
const inDetailBucket = bucketOf(bucketKey) < DETAIL_SAMPLE_RATE;

flashcatRum.init({
  applicationId: "<APPLICATION_ID>",
  clientToken: "<CLIENT_TOKEN>",
  sessionSampleRate: 100, // 会话全量采集，保证错误一条不漏
  // 重放对齐：细节用户内再抽 REPLAY_SAMPLE_RATE，其余用户永不录制（不接重放可省略本行）
  sessionReplaySampleRate: inDetailBucket ? REPLAY_SAMPLE_RATE : 0,
  trackResources: true,
  trackUserInteractions: true,
  trackLongTasks: true,
  beforeSend: (event) => {
    // 与 init() 前完全相同的判定，保证两处一致
    const isDetail = bucketOf(getCurrentUserId() || getOrCreateAnonId()) < DETAIL_SAMPLE_RATE;

    // 给每条留下来的事件盖章，标明这条会话是完整现场还是仅错误摘要
    event.context = {
      ...event.context,
      rum_sampling: isDetail ? "full" : "errors_only",
    };

    // 视图事件无法丢弃，显式放行以免触发 SDK 告警
    if (event.type === "view") return true;

    // 错误事件永远保留
    if (event.type === "error") return true;

    // 失败的请求永远保留
    if (event.type === "resource") {
      const statusCode = event.resource.status_code;
      if (statusCode === 0 || statusCode >= 400) return true;
    }

    // 其余数据只保留中签用户的
    return isDetail;
  },
});

由于分桶 key 跨会话不变，重放判定一次对整个用户生命周期都有效，也不存在会话续期后要重新判定的问题。

两种做法下，回放集合都严格是细节分桶的子集，最终录制比例是 DETAIL_SAMPLE_RATE × REPLAY_SAMPLE_RATE——与原生的 sessionSampleRate: 20 + sessionReplaySampleRate: 10 得到 2% 完全一致。

务必保留 rum_sampling 这类标记。 未中签的会话时间线天生是残缺的——只有视图、错误与失败请求。没有标记时，您在查看器里看到一条会话「没有任何点击」，无法判断是采样丢了还是用户真的没点。盖上标记后，缺失就有了解释：errors_only 的会话本就不含行为数据，而 full 的会话缺什么就是真的没发生。排查时先按 rum_sampling:full 过滤，就能只看完整现场。context 是 beforeSend 允许修改的字段，标记与丢弃决策写在同一个函数里，两者不会漂移。

必须按稳定的 key 分桶（会话或用户），不能用 Math.random() 逐事件抽签。逐事件随机在统计上是无害的——抽出来的是一份无偏样本，错误率、P75 这些聚合指标照样准确。问题出在排查单条会话的时候。设想一条会话依次产生了这些事件：进入商品页 → 点击「立即购买」 → 三个接口请求（其中下单接口返回 500） → 页面抛出异常。逐事件随机抽签后，错误与失败请求因为在白名单里被保留，而那个点击事件恰好没中签被丢掉。于是您在会话里看到的是：用户进了页面、什么都没做，然后接口失败并报错。真正的麻烦不是缺了一条数据，而是缺失的位置每条会话都不一样，且无法分辨——您看到会话里没有点击，无法判断是采样丢了，还是用户真的没点。会话从证据变成了不可信的证词。按稳定 key 分桶后，每条会话只有两种状态：中签的那部分现场完整，其余的明确只有错误与失败请求。两种都不会误导您。理由与哈希分桶一节相同。

使用前必须知道的三件事

数据量不会精确降到 20%：视图事件是会话骨架，无法丢弃，仍按 100% 上报。实际收敛比例取决于资源与行为事件在您数据中的占比。
绝对量指标需要换算：平台上会话数仍是 100%，但只有约 20% 的会话带完整数据。错误率、P75 这类比率与分位数指标不受影响（随机样本仍代表整体），但「资源请求总数」「点击次数」这类绝对量需要按 1 / 20% 换算。
会话重放要单独对齐一次：本方案把 sessionSampleRate 设成了 100，SDK 就以为每条会话都被完整采集，于是在全部会话里抽回放。少了对应 Tab 里的对齐那一步，回放会落到分桶之外的会话上——录像有了，可那条会话里根本没有行为数据。

和「只上报错误」那种配置的区别：那种做法是把非错误数据整体关掉，适合只关心错误、不做性能分析的场景；本方案保留两成完整现场，适合既要异常不漏、又要保留性能与行为分析能力的场景。

各端支持情况

平台	采样率生效时机	让新采样率立即生效
Web（浏览器）	每次页面加载 `init()` 时	支持，调用 `stopSession()`
微信小程序	每次冷启动 `init()` 时	支持，调用 `stopSession()`
iOS / Android	App 冷启动初始化时	默认下次冷启动生效；可通过 `stopInstance()` 重建立即生效（见进阶方案）
React Native	App 冷启动初始化时	不支持，下次启动生效

移动端默认建议「启动时读缓存值初始化 + 异步拉取最新值存缓存」的策略，新采样率在下次冷启动生效；确需立即生效的场景（如事故排查），参照进阶方案在安静的生命周期点重建 SDK 实例。

常见问题

把采样率从 20% 改成 100%，为什么有些用户还是没有数据？

存量会话的判定结果是粘滞的（规则 2）。修改前未中签的会话会保持静默直到过期（不活跃 15 分钟或持续 4 小时）。如果使用了动态配置方案，请确认在采样率变化时调用了 stopSession()。

采样率 20%，为什么实际采集的会话比例不是精确的 20%？

采样是独立概率抽签，不是配额（规则 3）。流量越大越接近设定值，小流量下波动是正常现象。如需要精确控制「哪些用户被采集」，请使用业务自定义采样的哈希分桶方案。

能不能只上报错误，不上报其他数据？

严格意义上的「只上报错误」做不到——视图（view）事件是会话的骨架，无法关闭。但可以做到非常接近，思路是两个相互独立的开关叠加使用：

采样率控制「哪些会话被采集」：以会话为单位，未命中的会话连错误也不上报（规则 1）。所以不能靠调低采样率来省量，那会同步丢掉错误。
事件开关控制「每个会话采集哪些事件」：trackResources、trackLongTasks、trackUserInteractions、trackWebVitals 与采样无关，对每一个被采集的会话都生效。

因此「尽量只看错误」的正确配置是：把 sessionSampleRate 开到 100 保证错误不漏，再用事件开关把非错误数据压下去。资源事件通常是数据量的大头，收敛它的收益最明显。

不要直接设置 trackResources: false。 浏览器端的 HTTP 5xx 和请求失败不是错误事件，而是带 status_code 的资源事件——RUM 的错误事件只来自 JS 运行时异常、console.error、浏览器 Report API 和手动 addError。关闭资源采集会让接口报错在平台上完全消失，而这往往正是您最想看的那类「错误」。

推荐的做法是保留资源采集，用 beforeSend 只丢弃成功的请求：

flashcatRum.init({
  applicationId: "<APPLICATION_ID>",
  clientToken: "<CLIENT_TOKEN>",
  sessionSampleRate: 100, // 全量采集会话，保证错误不漏
  trackResources: true, // 必须保持开启，否则接口报错不可见
  trackLongTasks: false,
  trackUserInteractions: false,
  trackWebVitals: false,
  beforeSend: (event) => {
    // 资源事件只保留失败的请求，成功的直接丢弃，不占用数据量
    if (event.type === "resource") {
      const statusCode = event.resource.status_code;
      return statusCode === 0 || statusCode >= 400;
    }
    return true;
  },
});

使用前请了解这套配置的三个代价：

视图事件仍会上报：每个页面至少一条，指标或事件计数变化时会节流更新，会话活跃期间每 5 分钟还有一次保活更新。这是无法消除的底噪，beforeSend 也无法丢弃视图事件。
错误现场只剩堆栈：关闭 trackUserInteractions 后，您无法知道用户点了什么才触发的错误，排查效率会明显下降。
链路追踪请求不受资源开关影响：命中 allowedTracingUrls 的请求即使关闭资源采集也仍会上报（标记为不索引，不计入数据量），因此流量并不会归零。

如果您的目标是「错误优先，但仍要保留现场」，请改用最佳实践三：错误与失败请求全量保留，其余数据按比例收敛，既压住数据量又留得下排查现场。

想把数据量降到 20%，但异常要全部上报，怎么配？

直接把 sessionSampleRate 设成 20 做不到——未命中的会话连错误也不上报（规则 1）。正确做法是会话全量采集保证错误不漏，再按会话或用户分桶，只让一部分会话保留完整数据。完整方案见最佳实践三。

快速开始

分析看板

SDK 接入

性能监控

异常追踪

查看器

会话重放

最佳实践

其他

理解 RUM 采样：机制、规则与最佳实践

采样是什么

采样的工作规则

1. 以会话为单位，而不是用户或事件

2. 判定结果在会话内粘滞

3. 是概率，不是精确配额

4. 采样率在初始化时固化

如何选择采样率

最佳实践一：让采样率可以动态调整

移动端进阶：让新采样率立即生效

最佳实践二：业务自定义采样

为什么用哈希分桶代替随机数

注意事项

最佳实践三：错误全量采集，其余数据按比例保留

使用前必须知道的三件事

各端支持情况

常见问题

​采样是什么

​采样的工作规则

​1. 以会话为单位，而不是用户或事件

​2. 判定结果在会话内粘滞

​3. 是概率，不是精确配额

​4. 采样率在初始化时固化

​如何选择采样率

​最佳实践一：让采样率可以动态调整

​移动端进阶：让新采样率立即生效

​最佳实践二：业务自定义采样

​为什么用哈希分桶代替随机数

​注意事项

​最佳实践三：错误全量采集，其余数据按比例保留

​使用前必须知道的三件事

​各端支持情况

​常见问题

采样是什么

采样的工作规则

1. 以会话为单位，而不是用户或事件

2. 判定结果在会话内粘滞

3. 是概率，不是精确配额

4. 采样率在初始化时固化

如何选择采样率

最佳实践一：让采样率可以动态调整

移动端进阶：让新采样率立即生效

最佳实践二：业务自定义采样

为什么用哈希分桶代替随机数

注意事项

最佳实践三：错误全量采集，其余数据按比例保留

使用前必须知道的三件事

各端支持情况

常见问题