RUM 配置¶

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

RUM 初始化¶

说明

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

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

字段	类型	必须	说明
`androidAppId`	`string`	Android 必填	Android RUM 应用 ID
`iosAppId`	`string`	iOS 必填	iOS RUM 应用 ID
`sampleRate`	`number`	否	会话采样率，范围 `0–1`
`sessionOnErrorSampleRate`	`number`	否	未被普通采样命中的错误会话补采样率，范围 `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 层的一种自动采集方式，并在测试环境检查是否产生重复数据。

RUM 手动埋点¶

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

属性类型¶

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

Action¶

添加即时 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 生命周期。完整配置见原生宿主 Hybrid 接入。

采样说明¶

sampleRate 和 sessionOnErrorSampleRate 必须是有限数值且位于 0–1。超出范围时 TypeScript 层会在初始化阶段抛出 RangeError。未传入时使用对应 Native SDK 的默认值。

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 数据边界¶

采样说明¶

相关专题¶

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

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