腾讯云可观测平台数据上报验证

本文介绍接入用户体验监控微信小程序 SDK 后，如何验证各监控能力的数据上报是否成功。
前提条件
验证期间建议开启 debug: true，方便观察初始化摘要与运行日志。
建议在微信开发者工具中打开 Network 面板，过滤采集域名。
步骤1：检查上报请求
初始化后应能看到三类请求，HTTP 2xx / 204均视为成功：
端点
内容
POST {endpoint}/api/v1/config
远程配置，body 为 { "project_key": "..." }
POST {endpoint}/api/v1/collect/mp-weixin
录制事件（回放原料）
POST {endpoint}/api/v1/collect/events
标准事件（错误 / 页面性能 / 接口测速 / 自定义事件）
重要：
远程配置关闭采集，或从未拉到配置且无缓存时，SDK 不会上报回放。这是默认保守策略，不是接入失败。
步骤2：验证各监控能力
验证录制与会话
1. 冷启动 → 打开页 A → 点击 → 跳到页 B → 切后台几秒再回前台。
2. 在控制台按平台 miniprogram 筛到该会话，页面跳转应在同一会话内。
3. 打开会话回放：画面由小程序引擎还原，事件时间轴与画面对齐。
录制通道会录入以下类型的事件：
type
来源
session_start
冷启动或超30分钟后台后新开会话
pageLoad
Page.onLoad
pageShow
Page.onShow
pageData
页面初始 data
setData
Page / Component 的 setData
event
用户手势（tap 等），可带点击坐标
scroll
onPageScroll
request / request_fail
wx.request（会忽略 SDK 自己的 collect 地址）
错误监控
SDK 初始化后自动监听 4 类错误来源，无需额外配置：
监听点
上报事件类型
说明
wx.onError
js_error
JS 运行时错误，可直接主动抛错验证
wx.onUnhandledRejection
promise_error
未处理的 Promise 拒绝；会过滤 request:fail，并跳过错误码为1 / 2 / 11–15 / 19 / 20 / 23的宿主提示
wx.onPageNotFound
js_error
页面不存在，mechanism_type 为 onPageNotFound
wx.onLazyLoadError
resource_error
分包 / 组件懒加载失败，resource_type = lazy_load
主动抛错验证：
setTimeout(() => { throw new Error('tdem verify error'); }, 0);
也可用未处理的 Promise 拒绝验证 promise_error：
Promise.reject(new Error('tdem verify rejection'));
错误上报位于 event_category = error，并带结构化字段 exception_stacks（含 type / value / mechanism_type / mechanism_handled）与 exception_frames；资源类错误另带 resource_type / element_tag。验证时在控制台确认这些字段已填充。
接口测速
SDK Hook 了 wx.request，接口请求会自动上报耗时与错误，无需额外配置。
页面性能
页面启动、注入、首屏、路由等指标依赖基础库 Performance API（建议 > 2.11.0），不可用时静默跳过。setData 更新性能统计依赖 setUpdatePerformanceListener（建议 > 2.12.0）。
挣扎事件
开启 struggleMonitor 后，命中规则会上报挣扎事件。需注意通道归属：挣扎事件不是独立的事件类型，而是统一走 POST {endpoint}/api/v1/collect/events，以 event_type = struggle、event_category = behavior 上报，具体类型落在 data.event_name。因此在控制台按 event_type = rage_click 过滤会查不到，需按 event_category = behavior 配合 event_name 查找。
规则版本 1.0.0，共9种自动检测类型，按所属规则组分开关：
子事件
所属组
默认
判定规则
rage_click
click
✅ 开
同一元素 rageClickWindowMs（默认1000ms）内连点达 rageClickCount（默认5）次
dead_click
click
✅ 开
点击后 deadClickWindowMs（默认3000ms）内未产生有效动作（页面跳转 / 接口成功 / 表单操作 / setData）
error_click
click
✅ 开
点击后 errorClickWindowMs（默认3000ms）内出现接口错误或 JS / Promise / 资源错误
slow_page
performance
❌ 关
页面 lcp / fcp / first_screen_time 三者最大值超过 slowPageThresholdMs（默认3000ms）
long_focus_time
form
❌ 关
单个表单控件持续聚焦超过 longFocusThresholdMs（默认20000ms）
uncompleted_form
form
❌ 关
页面退出时已改动字段占必填项（无必填项时取已触碰字段）比例达 incompleteMinFieldRatio（默认0.3），且期间未成功提交
form_zigzag
form
❌ 关
最近 4 次焦点切换呈 a → b → a → b 往复、且改动字段不少于2个，累计达 zigzagMinCount（默认2）次
form_validation_error
form
❌ 关
表单提交结果为失败（status = fail）
back_forward
navigation
❌ 关
页面浏览事件的导航类型为 back / forward，受 backForwardAsStruggle 控制（默认 true）
开关按规则组控制：click.enabled / performance.enabled / form.enabled / navigation.enabled，分别对应点击类、慢页面类、表单类、返回类规则；默认仅 click 为 true。
验证方式：开启对应规则组后按上表条件触发，在 Network 面板确认 POST {endpoint}/api/v1/collect/events 中出现 event_type = struggle、event_category = behavior，且 data.event_name 为对应子事件名。
以下为完整示例配置。顶层 sampleRate 为挣扎事件采样率（0 - 1，默认 1），throttleWindowMs 为同一子事件在同一目标上的节流窗口（毫秒，默认 3000），二者作用于全部子事件；其余配置项的含义与默认值见 SDK 初始化-挣扎监控。
const tdem = TDEM.init({
  projectKey: 'YOUR_PROJECT_KEY',
  endpoint: 'https://dem.rumt-zh.com',
  struggleMonitor: {
    enabled: true,
    sampleRate: 1,
    throttleWindowMs: 3000,
    click: {
      enabled: true,
      deadClickWindowMs: 3000,
      rageClickWindowMs: 1000,
      rageClickCount: 5,
      errorClickWindowMs: 3000,
    },
    // 以下三组默认关闭，按需开启
    performance: { enabled: false, slowPageThresholdMs: 3000 },
    form: {
      enabled: false,
      longFocusThresholdMs: 20000,
      incompleteMinFieldRatio: 0.3,
      zigzagMinCount: 2,
    },
    navigation: { enabled: false, backForwardAsStruggle: true },
  },
});
主动上报自定义挣扎
除规则引擎自动检测外，可用 trackStruggle(name, options) 主动上报业务侧挣扎：
tdem.trackStruggle('checkout_retry', {
  severity: 'high',               // low | medium | high，默认 medium
  tags: { channel: 'mp-weixin' },
  properties: { orderId: 'ORDER_123' },
});
name：非空字符串，最长 128 字符；为空或超限时仅打印 warning，不上报。
severity：仅接受 low / medium / high，非法值同样仅 warning。
上报形态为 event_name = custom_struggle、struggle_owner_type = business、detection_source = custom，并附带 custom_struggle_name。
验证方式：调用后在 Network 面板确认请求体中出现上述字段；同时可看到 struggle_severity / struggle_weight 已按 severity 换算（low / medium / high 对应 1 / 3 / 5）。
弱网与延迟上报
上报不是逐条即时发送的。未成功或无网时，录制段会先入内存缓冲，再落本地缓存，条件满足后自动补发。不了解这个机制，容易把正常的延迟上报误判为接入失败。
环节
触发条件
内存冲洗
满500条 / 满3MB / 每20s 定时 / 切后台（onAppHide）强制
本地持久化
缓存键 tdem_mp_replay_buffer_v1，上限2MB 或500条，超出先丢最旧
补发时机
回到前台（onAppShow）、联网时（wx.onNetworkStatusChange 且 isConnected）、远程配置放行后
补发顺序
按 segment_id 逐条发送，成功后从缓存删除
验证方式：
1. 断网（微信开发者工具可切换「离线」），操作几个页面产生事件。
2. 恢复网络或切后台再回前台，观察 Network 面板出现补发请求。
3. 在开发者工具 Storage 面板查看 tdem_mp_replay_buffer_v1，确认待补发数据随之上报并被清除。
注意：
初始化后20s 内未看到请求，可能是缓冲尚未冲洗，属正常现象。若远程配置未拉到且无缓存，SDK 会保守地不上报回放，详见 检查上报请求 中的说明。
验证脱敏
录制数据在离开设备前就会遮罩，因此「上报内容里的敏感字段是否已被替换」是数据上报验证的必要一环。配置项见 MP-03 的「脱敏（mask）」，此处只说明如何验证。
默认底线规则（不可关闭，也无「全明文」开关）：
密码类字段名（password / passwd / pwd / paypassword / paypwd 等）→ 输出 ******
11位手机号（字段名或自由文本）→ 形如 138****1234
18位校验通过的身份证号 → 形如 110101********1234
验证方式：
1. 在页面上输入一个手机号与一个身份证号（可使用测试值），触发一次上报。
2. 在 Network 面板查看对应请求体，确认敏感值已被替换为上述掩码形态，而非明文。
3. 若需额外字段遮罩，配置 mask.keys（按字段名）或 mask.fields（按 route.field / glob），再重复步骤1、2确认生效。
4. 表单输入框可在 WXML 上加 data-tdem-mask，使其按密码处理。
说明：
mask.allow 只能放宽非敏感字段的启发式扫描，试图用 allow 放行 password / phone / idcard 这类底线字段会被忽略。SDK 侧脱敏不能替代服务端的隐私处理。
步骤3：主动上报（可选）
除自动采集外，SDK 还提供主动上报接口。下面以 track 上报业务自定义事件为例，签名为 track(name, { tags, properties })。
tdem.track('pay_start', {
  tags: { source: 'banner' },
  properties: { amount: 99 },
});
name：必填，非空字符串；为空或非字符串时仅打印 warning，不上报。
tags / properties：可选，分别落到事件的 data.tags 与 data.event_properties；值会被转为字符串，单个值最长 1024 字符，请勿传嵌套对象。
上报形态为 event_type = custom、event_category = custom，data.event_name 即传入的 name。
验证方式：调用后在 Network 面板确认 POST {endpoint}/api/v1/collect/events 中出现 event_type = custom，且 data.event_name 为传入的事件名。完整签名与参数说明请参见《API 说明》。
步骤4：检查数据上报
在微信开发者工具 Network 面板中，观察 SDK 发往采集服务的事件上报请求（默认 POST 到 {endpoint}/api/v1/collect/events），或在控制台查看对应监控能力的数据。其中 {endpoint} 为初始化时填写的采集域名，国内站为 https://dem.rumt-zh.com。

type	来源
`session_start`	冷启动或超30分钟后台后新开会话
`pageLoad`	`Page.onLoad`
`pageShow`	`Page.onShow`
`pageData`	页面初始 `data`
`setData`	`Page` / `Component` 的 `setData`
`event`	用户手势（tap 等），可带点击坐标
`scroll`	`onPageScroll`
`request` / `request_fail`	`wx.request`（会忽略 SDK 自己的 collect 地址）

监听点	上报事件类型	说明
`wx.onError`	`js_error`	JS 运行时错误，可直接主动抛错验证
`wx.onUnhandledRejection`	`promise_error`	未处理的 Promise 拒绝；会过滤 `request:fail`，并跳过错误码为`1` / `2` / `11`–`15` / `19` / `20` / `23`的宿主提示
`wx.onPageNotFound`	`js_error`	页面不存在，`mechanism_type` 为 `onPageNotFound`
`wx.onLazyLoadError`	`resource_error`	分包 / 组件懒加载失败，`resource_type` = `lazy_load`

子事件	所属组	默认	判定规则
`rage_click`	`click`	✅ 开	同一元素 `rageClickWindowMs`（默认1000ms）内连点达 `rageClickCount`（默认5）次
`dead_click`	`click`	✅ 开	点击后 `deadClickWindowMs`（默认3000ms）内未产生有效动作（页面跳转 / 接口成功 / 表单操作 / `setData`）
`error_click`	`click`	✅ 开	点击后 `errorClickWindowMs`（默认3000ms）内出现接口错误或 JS / Promise / 资源错误
`slow_page`	`performance`	❌ 关	页面 `lcp` / `fcp` / `first_screen_time` 三者最大值超过 `slowPageThresholdMs`（默认3000ms）
`long_focus_time`	`form`	❌ 关	单个表单控件持续聚焦超过 `longFocusThresholdMs`（默认20000ms）
`uncompleted_form`	`form`	❌ 关	页面退出时已改动字段占必填项（无必填项时取已触碰字段）比例达 `incompleteMinFieldRatio`（默认0.3），且期间未成功提交
`form_zigzag`	`form`	❌ 关	最近 4 次焦点切换呈 a → b → a → b 往复、且改动字段不少于2个，累计达 `zigzagMinCount`（默认2）次
`form_validation_error`	`form`	❌ 关	表单提交结果为失败（`status` = `fail`）
`back_forward`	`navigation`	❌ 关	页面浏览事件的导航类型为 `back` / `forward`，受 `backForwardAsStruggle` 控制（默认 `true`）

端点	内容
`POST {endpoint}/api/v1/config`	远程配置，body 为 `{ "project_key": "..." }`
`POST {endpoint}/api/v1/collect/mp-weixin`	录制事件（回放原料）
`POST {endpoint}/api/v1/collect/events`	标准事件（错误 / 页面性能 / 接口测速 / 自定义事件）

环节	触发条件
内存冲洗	满500条 / 满3MB / 每20s 定时 / 切后台（`onAppHide`）强制
本地持久化	缓存键 `tdem_mp_replay_buffer_v1`，上限2MB 或500条，超出先丢最旧
补发时机	回到前台（`onAppShow`）、联网时（`wx.onNetworkStatusChange` 且 `isConnected`）、远程配置放行后
补发顺序	按 `segment_id` 逐条发送，成功后从缓存删除

数据上报验证

本页目录：

前提条件

步骤1：检查上报请求

步骤2：验证各监控能力

验证录制与会话

错误监控

接口测速

页面性能

挣扎事件

弱网与延迟上报

验证脱敏

步骤3：主动上报（可选）

步骤4：检查数据上报