Log 配置¶

本文说明 Cocos Creator 自定义日志、Console 自动采集和 RUM 关联配置。

Log 初始化¶

说明

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

guanceSdk.start({
  ...,
  logger: {
    sampleRate: 1,
    enableCustomLog: true,
    enableLinkRumData: true,
    printCustomLogToConsole: false,
    discardStrategy: 'discard',
    logLevelFilters: ['info', 'warning', 'error', 'critical', 'ok'],
    logCacheLimitCount: 5000,
    globalContext: {
      game_channel: 'app-store',
    },
  },
});

字段	类型	必须	说明
`sampleRate`	`number`	否	日志采样率，范围 `0–1`
`enableLinkRumData`	`boolean`	否	是否在日志中关联当前 RUM Session、View 等上下文
`enableCustomLog`	`boolean`	否	是否允许通过 Cocos API 写入自定义日志
`printCustomLogToConsole`	`boolean`	否	是否同时把自定义日志打印到原生控制台
`discardStrategy`	`discard` / `discardOldest`	否	达到缓存限制后丢弃新数据或最旧数据
`logLevelFilters`	`string[]`	否	允许采集的日志等级
`logCacheLimitCount`	`number`	否	Native SDK 本地日志缓存条数上限
`globalContext`	`Record<string, string>`	否	添加到所有日志的静态标签

sampleRate 超出 0–1 时初始化会抛出 RangeError。未传入的字段使用对应 Native SDK 默认值。

Logger 日志打印¶

使用 guanceSdk.logger.log() 前，需要在独立运行模式的 logger 配置中开启 enableCustomLog: true；原生宿主 Hybrid 模式需要由原生端开启自定义日志。

guanceSdk.logger.log(
  'battle started',
  'info',
  {
    battle_id: 'battle-001',
    player_count: 10,
  },
);

方法签名：

guanceSdk.logger.log(
  content: string,
  level?: string,
  attributes?: FTAttributes,
): void

level 默认值为 info。为保证 Android 与 iOS 行为一致，建议使用以下等级：

等级	说明
`info`	提示
`warning`	警告
`error`	错误
`critical`	严重
`ok`	恢复

虽然 TypeScript 类型允许自定义字符串，iOS Bridge 会把未知等级转换为 info，因此跨平台项目不应依赖自定义等级。

Console 自动采集¶

guanceSdk.start({
  ...,
  logger: {
    enableCustomLog: true,
    enableLinkRumData: true,
  },
  autoTrack: {
    console: true,
  },
});

开启后会包装以下方法，并在保留原控制台输出的同时写入 Log：

Console 方法	日志等级
`console.log`	`info`
`console.info`	`info`
`console.warn`	`warning`
`console.error`	`error`

对象参数会优先使用 JSON.stringify() 转为文本，无法序列化时使用 String()。

采集边界

console: true 可能采集调试信息、账号、Token 或业务对象。生产环境应先审查 Console 内容，必要时保持关闭并只使用经过筛选的 guanceSdk.logger.log()。

调用 guanceSdk.shutdown() 后，SDK 会恢复原始 Console 方法。

RUM 关联¶

要建立日志与当前 RUM View 的关联，需要同时满足：

已初始化 RUM；
当前存在有效 View；
enableLinkRumData 为 true。

如果日志早于首个 View 产生，或 RUM 未命中采样，关联字段可能为空。

属性与缓存¶

globalContext 适合所有日志共享的字符串标签。
attributes 适合单条日志，可使用字符串、数值、布尔值、数组和 JSON 对象。
当前 Cocos API 未暴露手动 Flush；缓存、批量与上传时机由 Native SDK 管理。
日志内容和属性不得包含密码、Token 或完整个人敏感信息，详见数据与隐私。