RUM 配置¶

本文说明 Cocos Creator RUM 初始化参数、自动采集范围和 Native 监控配置。

RUM 初始化¶

说明

本页代码示例中的 ... 表示已省略 sdk 基础配置（例如 datakitUrl）。请先参照 SDK 初始化完成通用配置；本页仅展示 RUM 相关配置。

百分比采样字段的适用构建

以下示例使用开发分支中的百分比采样字段，版本范围见采样字段的适用范围。使用 0.1.0-alpha.7 时，请将 sessionSamplingRate: 100 改为 sampleRate: 1，将 sessionOnErrorSamplingRate: 0 改为 sessionOnErrorSampleRate: 0。

guanceSdk.start({
  ...,
  rum: {
    androidAppId: 'android-rum-app-id',
    iosAppId: 'ios-rum-app-id',
    sessionSamplingRate: 100,
    sessionOnErrorSamplingRate: 0,
    enableNativeCrash: true,
    enableNativeAnr: true,
    globalContext: {
      game_mode: 'ranked',
    },
  },
});

字段	类型	必须	说明
`androidAppId`	`string`	Android 必填	Android RUM 应用 ID
`iosAppId`	`string`	iOS 必填	iOS RUM 应用 ID
`sessionSamplingRate`	`number`	否	会话采样百分比，范围 `0–100`，允许小数；默认 `100`
`sessionOnErrorSamplingRate`	`number`	否	未被普通采样命中的错误会话补采样百分比，范围 `0–100`，允许小数；默认 `0`
`sampleRate`	`number`	否	已废弃，建议使用 `sessionSamplingRate`；保留原来的 `0–1` 单位和行为
`sessionOnErrorSampleRate`	`number`	否	已废弃，建议使用 `sessionOnErrorSamplingRate`；保留原来的 `0–1` 单位和行为
`enableNativeUserAction`	`boolean`	否	是否采集原生 UI Action
`enableNativeUserView`	`boolean`	否	是否采集原生页面 View
`enableNativeUserResource`	`boolean`	否	是否自动采集原生网络 Resource
`enableNativeCrash`	`boolean`	否	是否采集 Native Crash
`enableNativeAnr`	`boolean`	否	是否采集 Native ANR
`enableNativeUiBlock`	`boolean`	否	是否采集 Native UI 卡顿或 Freeze
`nativeUiBlockDurationMs`	`number`	否	Native UI 卡顿阈值，单位毫秒；仅在开启 `enableNativeUiBlock` 时生效
`errorMonitorType`	`number`	否	错误事件附加监控项的 Native SDK 位掩码
`deviceMetricsMonitorType`	`number`	否	View 设备指标监控项的 Native SDK 位掩码
`detectFrequency`	`normal` / `frequent` / `rare`	否	设备指标检测频率
`globalContext`	`Record<string, string>`	否	添加到 RUM 数据的静态全局标签

Android 运行时要求 androidAppId，iOS 运行时要求 iosAppId。同一份跨平台 TypeScript 配置可以同时传入两个值。

errorMonitorType 与 deviceMetricsMonitorType 直接透传数字位掩码，应与当前 Native SDK 版本的定义保持一致。具体组合参考 Android RUM 配置和 iOS RUM 配置。

Cocos 自动采集¶

自动采集通过 guanceSdk.start() 的 autoTrack 配置开启，所有选项默认关闭：

guanceSdk.start({
  ...,
  rum: {
    androidAppId: 'android-rum-app-id',
    iosAppId: 'ios-rum-app-id',
  },
  logger: {
    enableCustomLog: true,
  },
  trace: {
    traceType: 'ddTrace',
  },
  autoTrack: {
    scenes: true,
    actions: true,
    errors: true,
    console: false,
    network: true,
  },
});

字段	采集行为	依赖
`scenes`	场景启动时关闭前一个 View，并以场景名启动新 View	RUM
`actions`	全局 `TOUCH_END` 转换为 Action；优先使用事件目标节点名，并附加触摸坐标	RUM
`errors`	监听未捕获 JavaScript Error 与 Promise rejection	RUM；运行时需同时提供 `globalThis.addEventListener` 和 `globalThis.removeEventListener`
`console`	包装 `console.log/info/warn/error` 并转换为自定义日志	Log；详见 Log 配置
`network`	包装 `fetch` 与 `XMLHttpRequest`，采集 Resource 并注入 Trace Header	RUM；Trace Header 还要求初始化 Trace

调用 guanceSdk.shutdown() 时会还原 Console、Fetch、XHR 和场景/触摸监听器。

JavaScript 错误自动采集的运行时前提

开启 autoTrack.errors 后，SDK 通过全局 error 和 unhandledrejection 事件采集未捕获的 JavaScript 异常与未处理的 Promise rejection。只有当前 Cocos JavaScript 运行时同时提供 globalThis.addEventListener 和 globalThis.removeEventListener 时，SDK 才会注册这两个监听器。

如果运行时不提供上述 API，errors: true 不会安装错误监听器，也不会抛出初始化错误。业务代码已经捕获的异常不会触发全局事件，需要调用 guanceSdk.rum.addError() 手动上报。

避免重复采集

autoTrack.actions 与 enableNativeUserAction、autoTrack.network 与 enableNativeUserResource 可能覆盖同一交互或请求。应根据实际请求栈选择 Cocos 层或 Native 层的一种自动采集方式，并在测试环境检查是否产生重复数据。

Android 推荐开启 autoTrack.network，保持原生 setEnableHttpURLConnectionResource(false)，避免同一次 XHR 被两层采集。参见 Android 网络采集建议。

RUM 手动埋点¶

自动采集无法覆盖自定义页面、业务操作、已捕获异常、自定义网络栈等场景时，可以通过 guanceSdk.rum 手动上报。独立运行模式需要先在 guanceSdk.start() 中初始化 rum；原生宿主 Hybrid 模式需要由原生端先初始化 RUM。

属性类型¶

以下方法中的 attributes 均为可选参数，支持 JSON 可序列化的字符串、数值、布尔值、null、数组和对象。

Action¶

startAction 与 addAction 的使用区别

startAction 内部会自动计算 Action 耗时，计算期间会尽量与附近发生的 Resource、LongTask、Error 数据进行关联，并设有 100 ms 频繁触发保护，建议用于用户操作类型的数据。
如果需要频繁调用，请使用 addAction。通过 addAction 上报的 Action 不会与 startAction 发生冲突，也不会与当前的 Resource、LongTask、Error 数据进行关联。

添加即时 Action：

guanceSdk.rum.addAction('Use Skill', 'click', {
  skill_id: 'fireball',
});

启动由 Native SDK 管理关联生命周期的 Action：

guanceSdk.rum.startAction('Matchmaking', 'custom', {
  queue: 'ranked',
});

方法签名：

guanceSdk.rum.addAction(
  name: string,
  type?: string,
  attributes?: FTAttributes,
): void

guanceSdk.rum.startAction(
  name: string,
  type?: string,
  attributes?: FTAttributes,
): void

name 和 type 不能为空，type 默认值为 click。

开启 autoTrack.actions 后，全局触摸结束事件会自动生成 Action。对于同一次触摸，不要同时调用手动 Action API。

View¶

启动 View：

guanceSdk.rum.startView('Battle', {
  map_id: 'map-001',
});

结束当前 View：

guanceSdk.rum.stopView({
  battle_result: 'victory',
});

方法签名：

guanceSdk.rum.startView(name: string, attributes?: FTAttributes): void
guanceSdk.rum.stopView(attributes?: FTAttributes): void

name 不能为空。应用应保证 View 成对结束；启动新 View 前先结束旧 View。

开启 autoTrack.scenes 后，SDK 会自动管理场景 View。不要再为同一场景手动调用 View API，以免产生重复或嵌套错误。

Error¶

try {
  startBattle();
} catch (error) {
  const exception = error instanceof Error
    ? error
    : new Error(String(error));

  guanceSdk.rum.addError(
    exception.message,
    exception.stack || '',
    'game_logic_error',
    'run',
    {
      scene: 'Battle',
    },
  );
}

方法签名：

guanceSdk.rum.addError(
  message: string,
  stack: string,
  type?: string,
  state?: 'run' | 'startup' | 'unknown',
  attributes?: FTAttributes,
): void

参数	默认值	说明
`message`	无	错误信息
`stack`	无	错误堆栈
`type`	`cocos_error`	业务错误类型
`state`	`run`	发生阶段：运行、启动或未知
`attributes`	无	当前错误附加属性

开启 autoTrack.errors 后，未捕获 JavaScript Error 和 Promise rejection 会自动上报。业务已捕获并手动上报的异常不会被全局监听器再次捕获。

LongTask¶

guanceSdk.rum.addLongTask(
  'GenerateWorld',
  850 * 1_000_000,
  {
    map_size: 'large',
  },
);

方法签名：

guanceSdk.rum.addLongTask(
  stack: string,
  durationNs: number,
  attributes?: FTAttributes,
): void

durationNs 的单位为纳秒。Cocos JavaScript 层当前不自动识别 LongTask，需要由业务在已知耗时任务结束后调用。

Resource¶

完整 Resource 由三个阶段组成：

startResource()：开始计时；
stopResource()：结束计时；
addResource()：补充请求内容与可选性能指标。

export async function requestMatch(): Promise<void> {
  const key = `match-${Date.now()}`;
  const url = 'https://api.example.com/match';
  const started = Date.now() * 1_000_000;

  guanceSdk.rum.startResource(key, {
    request_source: 'matchmaking',
  });

  try {
    const traceHeaders = guanceSdk.trace.getHeaders(url, key);
    const response = await fetch(url, {
      headers: traceHeaders,
    });
    const ended = Date.now() * 1_000_000;

    guanceSdk.rum.stopResource(key);
    guanceSdk.rum.addResource(
      key,
      {
        url,
        httpMethod: 'GET',
        requestHeaders: traceHeaders,
        statusCode: response.status,
        responseContentType: response.headers.get('content-type') || undefined,
      },
      {
        fetchStartTime: started,
        responseStartTime: ended,
        responseEndTime: ended,
      },
    );
  } catch (error) {
    guanceSdk.rum.stopResource(key);
    const exception = error instanceof Error
      ? error
      : new Error(String(error));
    guanceSdk.rum.addError(
      exception.message,
      exception.stack || '',
      'network_error',
    );
  }
}

方法签名：

guanceSdk.rum.startResource(
  key: string,
  attributes?: FTAttributes,
): void

guanceSdk.rum.stopResource(
  key: string,
  attributes?: FTAttributes,
): void

guanceSdk.rum.addResource(
  key: string,
  content: FTResourceContent,
  metrics?: FTResourceMetrics,
): void

Resource 内容¶

字段	类型	必须	说明
`url`	`string`	是	完整请求 URL
`httpMethod`	`string`	是	HTTP 方法
`requestHeaders`	`Record<string, string>`	否	请求头
`responseHeaders`	`Record<string, string>`	否	响应头
`responseBody`	`string`	否	响应 Body；可能包含敏感数据，谨慎采集
`statusCode`	`number`	否	HTTP 状态码
`responseContentType`	`string`	否	响应 Content-Type
`responseContentEncoding`	`string`	否	响应 Content-Encoding

Resource 性能指标¶

所有时间字段单位均为纳秒：

字段	说明
`fetchStartTime`	请求开始时间
`tcpStartTime`	TCP 连接开始时间
`tcpEndTime`	TCP 连接结束时间
`dnsStartTime`	DNS 解析开始时间
`dnsEndTime`	DNS 解析结束时间
`responseStartTime`	响应开始时间
`responseEndTime`	响应结束时间
`sslStartTime`	TLS 连接开始时间
`sslEndTime`	TLS 连接结束时间

key 在三个 RUM 方法和 guanceSdk.trace.getHeaders() 中必须一致。

自动与手动二选一

开启 autoTrack.network 后，fetch 和 XMLHttpRequest 已自动采集。不要再对同一个请求执行上述手动 Resource 流程。

上传行为¶

当前 Cocos API 未暴露手动 Flush。事件写入 Native SDK 后，由 Native SDK 根据其缓存和上传策略发送。应用关闭前不要依赖 guanceSdk.shutdown() 强制上传。

Cocos 与 Native 数据边界¶

scenes、actions、errors、network 采集 Cocos JavaScript 层行为。
enableNative* 选项采集 Android/iOS 原生容器行为。
Native Crash、ANR、UI Block 和设备指标由底层 Android/iOS SDK 生成。
Cocos Long Task 当前不自动采集，需要调用手动 API。
自动网络采集只覆盖当前运行时实际提供的 fetch 和 XMLHttpRequest。

原生 App 只在部分页面使用 Cocos 时，按原生 SDK 要求完成初始化，并通过 enterCocos() 和 leaveCocos() 在 Cocos 页面可见期间切换 View 生命周期。完整配置见原生与 Cocos 混合开发。

采样说明¶

新采样字段统一使用百分数：0 表示关闭，1 表示 1%，20 表示 20%，100 表示全量；0.1 表示 0.1%，不会按 0–1 比例猜测单位。

sessionSamplingRate、sessionOnErrorSamplingRate 必须是有限数值且位于 0–100。NaN、Infinity、负数和大于 100 的值会在 TypeScript 初始化阶段抛出 RangeError，不会截断或回退到旧字段。
仅使用旧的 sampleRate、sessionOnErrorSampleRate 时，仍按 0–1 校验，默认值和行为保持不变。旧的 sampleRate: 1 等价于新的 sessionSamplingRate: 100。
同一采样项同时提供新旧字段时，优先使用已设置的新字段，包括显式的 0；对应旧字段不会参与校验，也不会下发。例如 { sessionSamplingRate: 0, sampleRate: 1 } 会关闭普通会话采样。
新旧字段均未设置时，使用对应 Native SDK 的默认值；普通 RUM 会话采样默认 100，错误会话补采样默认 0。

Log、Trace 和 Replay 的新旧字段遵循相同的优先级与校验规则，具体字段见 Log 配置、Trace 配置和 Cocos Creator 会话重放。

iOS 小数百分比

0–100 的整数配置可通过当前 iOS Bridge 直接传给原生 SDK。小数百分比还要求原生 SDK 的配置、传递和实际采样链路支持浮点数；当前 Cocos 依赖的 iOS 1.6.8-alpha.5 使用整数采样属性，传入 0.1 或 99.9 等小数时 Bridge 会明确报错，不会静默截断或四舍五入。

Android Bridge 会将新百分比字段除以 100 后传给原生比例采样接口。iOS 小数采样应在安装支持完整浮点采样链路的原生版本后验证，不能仅凭 TypeScript 类型或配置校验通过判断支持情况。

RUM 配置¶

RUM 初始化¶

Cocos 自动采集¶

RUM 手动埋点¶

属性类型¶

Action¶

View¶

Error¶

LongTask¶

Resource¶

Resource 内容¶

Resource 性能指标¶

上传行为¶

Cocos 与 Native 数据边界¶

采样说明¶

相关专题¶

文档内容是否对您有帮助？

RUM 配置¶

RUM 初始化¶

Cocos 自动采集¶

RUM 手动埋点¶

属性类型¶

Action¶

View¶

Error¶

LongTask¶

Resource¶

Resource 内容¶

Resource 性能指标¶

上传行为¶

Cocos 与 Native 数据边界¶

采样说明¶

相关专题¶

文档内容是否对您有帮助？ ×

文档内容是否对您有帮助？