小程序日志采集¶

小程序 Logs SDK 用于向 观测云 发送业务日志，并自动采集控制台、运行时和网络错误。日志写入 browser_log 来源，可在日志查看器中检索；与 MiniApp RUM SDK 配合使用时，可关联应用、会话、页面和用户信息。

本文按 SDK 1.0.6 说明接入方式与行为。版本变化见 SDK 更新日志。

开始使用¶

1. 安装与引入¶

推荐通过 npm 安装，使用 datafluxLogs 入口：

npm install @cloudcare/dataflux-rum-miniapp-logs

在应用入口引入 SDK，并在业务日志和请求发生前完成初始化。使用原生小程序开发工具时，按工具要求完成 npm 构建。

const { datafluxLogs } = require('@cloudcare/dataflux-rum-miniapp-logs')

也可以下载 SDK 文件，放入小程序项目后从本地路径引入。以下路径应按文件实际位置调整：

const { datafluxLogs } = require('./dataflux-rum-miniapp-logs.js')

SDK 自动选择可用的 wx、my、swan、tt 或 uni 请求接口，分别适配微信、支付宝、百度、抖音和 uni 宿主；多个接口同时存在时按上述顺序选择。使用 uni 工程时，应在小程序端代码中引入和初始化。设备、网络、存储或生命周期接口缺失时独立降级；没有可用请求接口时不采集日志，并输出初始化提示。

SDK 运行于小程序宿主，安装包不设置 engines.node 限制。Node.js 仅用于开发阶段的构建、测试和发布工具，其版本需满足对应开发依赖的要求。

2. 初始化¶

选择一种上报方式，在应用生命周期内初始化一次。上报地址必须可从小程序访问，并按目标平台要求配置请求域名。

datafluxLogs.init({
  datakitOrigin: 'https://datakit.example.com',
  applicationId: '<APPLICATION_ID>',
  service: 'miniapp',
  env: 'prod',
  version: '1.0.0'
})

datafluxLogs.init({
  site: '<PUBLIC_DATAWAY_URL>',
  clientToken: '<CLIENT_TOKEN>',
  applicationId: '<APPLICATION_ID>',
  service: 'miniapp',
  env: 'prod',
  version: '1.0.0'
})

重复调用 init() 不会更新配置。silentMultipleInit: true 仅关闭重复初始化提示。

3. 发送并查看日志¶

初始化后，在同一模块使用 datafluxLogs；其他页面可按前述方式引入同一个 SDK 模块。

datafluxLogs.logger.info('应用启动', { entry: 'home' })
datafluxLogs.logger.warn('库存不足', { product_id: 'product-123' })
datafluxLogs.logger.error('支付失败', { order_id: 'order-123' })

日志按批次发送，默认每 30 秒尝试发送一次；达到批次阈值或应用进入后台时也会触发发送。进入日志查看器，按来源 browser_log、service、日志正文或自定义字段检索。

配置¶

初始化参数¶

除所选上报方式要求的地址和令牌外，其他参数均可选。采样在 SDK 初始化时确定，同一运行实例内沿用该结果，并非每条日志独立随机采样。

从 1.0.6 起，移除未实现的初始化选项 tags、trackInteractions、allowedTracingOrigins、traceId128Bit 和 traceType。自定义字段改用上下文 API；交互与链路采集在 RUM SDK 中配置。

使用¶

日志等级¶

默认 Logger 为 datafluxLogs.logger，默认等级为 debug，默认通过 HTTP 上报。可直接调用对应方法：

message 为字符串，context 是可选的字段对象。也可以使用 log(message, context, status) 显式指定等级；省略 status 时为 info。注意 warn() 对应的状态值是 warning：

datafluxLogs.logger.log('库存不足', { product_id: 'product-123' }, 'warning')

使用 setLevel() 设置最低等级，低于该等级的日志不输出。等级顺序为 debug → info → warning → error → critical：

datafluxLogs.logger.setLevel('warning')

自定义 Logger¶

为不同业务模块创建 Logger，分别设置等级、输出方式和持久上下文：

const paymentLogger = datafluxLogs.createLogger('payment', {
  level: 'info',
  handler: 'http',
  context: { module: 'payment' }
})

paymentLogger.info('创建订单', { order_id: 'order-123' })

createLogger(name, configuration) 返回创建的 Logger；之后可通过 getLogger(name) 获取。未创建过的名称返回 undefined。configuration 中的 level、handler、context 都可省略，默认分别为 debug、http 和空对象。

使用 setHandler() 切换输出方式：

const paymentLogger = datafluxLogs.getLogger('payment')
if (paymentLogger) {
  paymentLogger.setHandler('console')
}

自动采集的错误由默认 Logger 输出，因此修改 datafluxLogs.logger 的等级或输出方式，也会影响自动错误日志。命名 Logger 的设置只作用于该 Logger。

自定义字段¶

自定义字段可以放在全局上下文、Logger 上下文或单条日志上下文中。HTTP 上报时，同名自定义字段按全局 → Logger → 单条日志的顺序覆盖。

全局上下文作用于所有 Logger 的 HTTP 日志：

datafluxLogs.setLoggerGlobalContext({ tenant: 'example' })
datafluxLogs.addLoggerGlobalContext('region', 'cn')
const globalContext = datafluxLogs.getLoggerGlobalContext()
datafluxLogs.removeLoggerGlobalContext('region')

Logger 上下文只作用于对应 Logger：

datafluxLogs.logger.setContext({ team: 'payments' })
datafluxLogs.logger.addContext('channel', 'miniapp')
datafluxLogs.logger.removeContext('channel')

setLoggerGlobalContext() 和 setContext() 替换对应的整份上下文；add...Context() 添加或替换一个字段，remove...Context() 删除一个字段。获取全局上下文返回独立快照，修改返回对象不会修改 SDK 内部保存的数据。

单条日志上下文仅作用于本次调用：

datafluxLogs.logger.info('支付完成', {
  order_id: 'order-123',
  amount: 0,
  paid: true,
  customer: { id: 'customer-123' },
  items: ['product-123']
})

字段支持标量、对象和数组。0、false 等有效值会保留；对象和数组在上报时序列化为 JSON 字符串，BigInt 按精确十进制字符串发送。普通业务字段可以直接放在上下文根级，也兼容 tags: { ... } 写法；这里的 tags 最终仍作为自定义日志字段发送。

上下文采用独立快照。有 toJSON(key) 的对象会在原实例上按实际字段名完成序列化，再保存结果，支持带私有字段的脱敏器。普通字段的脱敏器失败时使用错误占位值，不回退到未脱敏原对象。

HTTP 日志的根上下文和嵌套 tags 只接受字典结果；无效结果被忽略并保留有效持久字段。设置持久上下文时，若根脱敏器失败或返回非字典，则重置为空字典。单条日志不会修改持久上下文。

业务字段应避免与 message、status、service 等标准字段同名；同名业务数据可放在 business 对象中。message 和 status 由日志调用参数决定，type 固定为 SDK 内部日志类型，不能通过上下文替换。

手动记录错误¶

logger.error() 接收正文和上下文。需要记录 Error 的堆栈时，将其明确放到 error.stack：

const error = new Error('支付接口超时')
datafluxLogs.logger.error(error.message, {
  order_id: 'order-123',
  error: { stack: error.stack }
})

手动错误默认上报 error_source=logger。单条日志显式传入的 error.source 可以覆盖默认来源；自动错误保留实际来源。

自动错误采集¶

默认开启，可通过 forwardErrorsToLogs: false 关闭。采集能力取决于宿主提供的 API：

网络错误自动采集需要业务调用已提供 success、fail 或 complete 回调，并使用可安全复制的普通参数对象。冻结对象、空原型字典、不可枚举数据属性、Symbol 元数据以及响应式 Proxy 的有效值均可保留；原回调参数、返回值、异常和原生 task/Promise 保持不变。

以下情况不会自动生成请求完成日志：

• 调用未提供任何回调。SDK 不注入回调，也不读取或订阅业务 Promise，以保留原有返回模式和未处理拒绝事件。
• 参数含访问器或特殊原型。SDK 将原参数交给宿主，保留原有读取行为。
• 请求属于 Logs 自身或已排除的 RUM 上传地址。

HTTP 4xx 不会仅因状态码生成错误日志。业务已捕获的失败可用 logger.error() 手动记录；未处理拒绝仍可由宿主运行时 hook 采集。成功请求和被排除的上传请求不会读取响应正文。

关联 RUM¶

Logs 可以独立使用。需要关联用户访问上下文时，按 MiniApp RUM 接入文档初始化 RUM SDK。RUM 上下文可用时，日志附带相应应用、会话、页面、操作和用户信息；不可用时仍可上报独立日志。

SDK 按日志发生时刻获取 RUM 上下文。延迟错误的历史资料缺失或过期时省略对应字段，不用当前页面替代。没有 RUM 关联时，普通即时日志仍可附带当前页面路由，但不会凭空生成 RUM 页面 ID。

Logs 自动排除自身上传地址，以及同一采集地址下的 /v1/write/rum。如果 RUM 与 Logs 使用不同域名、端口或代理路径，设置可选的 rumIntakeUrls，防止上传失败时相互采集：

datafluxLogs.init({
  datakitOrigin: 'https://logs.example.com',
  rumIntakeUrls: ['https://rum.example.com/v1/write/rum']
})

上述配置应并入最初的 init()，不要重复初始化。列表仅接受完整 HTTP(S) URL，初始化时保存快照，无效项会被忽略。比较时统一协议、主机名大小写和默认端口，忽略 query/fragment，保留完整路径及其大小写；不会排除同域名下其他业务路径。

上报字段¶

logger.log() 等记录日志的方法返回 void，不会返回日志对象。SDK 将数据写入 browser_log 来源；以下为日志查看器中常用字段，而非一个固定的嵌套 JSON 返回结构。

platform 表示小程序宿主，操作系统使用 os 等独立字段。device_uuid 是 SDK 生成并保存到本地存储的匿名安装标识，不是宿主 AppID 或硬件 ID；清除存储后重新生成，存储不可用时仅在当前运行期间稳定。

上报时机与限制¶

这些是 SDK 的内置发送行为，不是公开初始化选项。较大的对象或响应正文会增加单条日志体积，建议只记录排查需要的业务字段。

常见问题¶

SDK 更新日志¶

1.0.6（2026-09-09）¶

功能与兼容性¶

• 完善微信、支付宝、百度、抖音和 uni 宿主的自动检测，以及设备、网络、存储和生命周期接口的兼容处理；可选接口不可用时安全降级。
• 独立使用 Logs 时支持通过 applicationId 上报应用 ID；关联 RUM 时按日志发生时刻获取上下文，避免延迟错误关联到当前页面或会话。
• 新增可选 rumIntakeUrls，用于排除独立采集地址的 RUM 上传；同一采集地址下的 Logs/RUM 上传自动排除，避免上传失败后相互采集。
• 补齐公开 TypeScript 声明和发布包中的类型入口；移除 engines.node 安装限制，SDK 运行时不依赖 Node.js。仓库构建、测试和发布工具仍需满足各开发依赖的 Node.js 要求。

问题修复¶

• 修复请求和下载拦截对原参数、业务回调、返回 task/Promise 及未处理拒绝事件的影响；保留响应式参数的有效值，采集异常不再影响业务调用。成功请求及排除的上传请求不再读取响应正文。
• 修复上下文串改、危险属性合并和脱敏结果错误复用；在原对象上按实际字段名执行 toJSON(key) 并保存独立快照，支持私有字段脱敏器、对象、数组和 BigInt。
• 修复根上下文及嵌套 tags 返回非字典或脱敏失败时产生数字字段、丢失已有字段的问题；无效上下文不会回退为未脱敏原值，单条日志不会修改持久上下文。
• 修复运行时错误和未处理拒绝的多行正文、原始堆栈及网络诊断字段丢失；手动错误日志默认来源正确上报为 logger，自动错误保留实际来源。
• 修复上报字段转义、Unicode 字节计数、0/false 等有效值丢失及批次重入问题；应用进入后台时及时刷新日志。platform 正确表示宿主，device_uuid 使用本地持久化的匿名安装标识。

升级说明¶

• 移除未实现的初始化选项 tags、trackInteractions、allowedTracingOrigins、traceId128Bit 和 traceType；自定义字段使用上下文 API，交互与链路采集由 RUM SDK 配置。
• 无回调调用，以及包含访问器或特殊原型的请求参数，会保持宿主原有行为，不自动生成请求完成日志；业务已捕获的失败可通过 logger.error() 手动记录，未处理拒绝仍可由宿主运行时 hook 采集。