GCL-ET Monitor SDK

GCL 浏览器监控 SDK，统一采集异常、性能、页面访问、路由、点击、停留时长和登录事件。

本包为 GCL-ET 内部项目使用的专有软件，发布在 npm 公共仓库仅用于团队项目安装，不授予外部使用许可。

安装

npm install @gcl-et/monitor-sdk

使用

import {
  captureEvent,
  captureException,
  initMonitor,
  setTraceId,
  setUser,
  trackLogin,
} from '@gcl-et/monitor-sdk';

initMonitor({
  appId: 'gcl-trade-web',
  endpoint: 'https://bff.example.com/monitor/events',
  release: '1.0.0',
  env: 'prod',
  sampleRate: 1,
  behaviorSampleRate: 1,
  sessionTimeout: 30 * 60 * 1000,
  batchSize: 10,
  flushInterval: 2000,
  maxRetries: 2,
  apiCodeField: 'code',
  apiSuccessCodes: [200, '200'],
  apiMessageFields: ['msg', 'message', 'error'],
  trackPageViews: true,
  trackClicks: true,
  trackStayDuration: true,
  captureClickText: false,
  beforeSend(event) {
    return event;
  },
});

setUser('user-id');
setTraceId('backend-trace-id');
trackLogin('user-id', { loginType: 'password' });

captureEvent('business', {
  message: 'order_created',
  extra: { orderId: 'masked-order-id' },
});

try {
  throw new Error('business error');
} catch (error) {
  captureException(error, {
    module: 'order',
  });
}

事件字段

SDK 上报的核心字段：

• appId：应用 ID
• release：发布版本，后续用于 sourcemap 反解
• env：运行环境，支持 dev、test、staging、prod
• type：事件类型
• message：异常信息
• stack：异常堆栈
• url：当前页面地址
• userId：用户标识
• sessionId：SDK 自动生成的会话标识，默认 30 分钟无操作后更新
• traceId：前后端链路追踪标识
• breadcrumbs：用户行为轨迹
• extra：插件或业务传入的扩展信息
• eventId：SDK生成的事件唯一标识，网络重试时用于服务端去重

本地开发

npm install
npm run typecheck
npm run build

当前能力

• 自动捕获 window.error
• 自动捕获 unhandledrejection
• 忽略 script、link、img 等资源加载失败，避免全量发布产生无效异常
• 忽略旧 chunk、动态模块和预加载 CSS 失效等发布过程异常
• 自动监控 fetch HTTP 状态失败和业务响应码失败
• 自动监控 XMLHttpRequest HTTP 状态失败和业务响应码失败
• 无 HTTP 响应的网络失败、CORS、主动取消和页面跳转中断不上报接口异常
• 默认将响应 JSON 中 code 不为数字或字符串 200 的请求记录为 api_error
• 业务响应码为数字 600 或字符串 "600" 时不上报接口异常
• 接口异常记录请求地址、方法、查询参数、请求体和响应体
• 密码、Token、Cookie 等敏感字段自动脱敏，超长内容自动截断
• 自动记录点击行为 breadcrumbs
• 自动上报首次页面访问和 SPA 路由切换
• 自动上报页面可见停留时长
• 自动上报点击事件，忽略输入框和文本域的输入内容
• 默认不采集点击元素文本，只有显式设置 captureClickText: true 才采集
• 默认移除URL账号、查询参数及非路由hash，避免泄露token等敏感信息
• 支持 trackLogin 记录登录次数
• 支持 captureEvent('business', ...) 上报业务自定义事件
• 自动携带浏览器、系统、设备类型和网络类型
• 自动采集基础 navigation timing 和 FCP 白屏时间
• 支持 beforeSend 过滤或脱敏
• 支持 sampleRate 采样
• 支持独立的 behaviorSampleRate 行为事件采样
• 默认每2秒或累计10条事件批量发送到 {endpoint}/batch
• 批量请求失败默认重试2次，页面关闭时使用 sendBeacon 立即发送
• 服务端批量接口不可用时自动回退到原有单事件接口

行为统计说明

• 首次进入页面发送 page_view
• SPA 地址变化发送 route_change，服务端按一次访问统计
• 路由离开、页面切到后台或关闭时发送 stay_duration
• 点击发送 click，同时保留为异常事件的 breadcrumb
• 登录成功后由业务显式调用 trackLogin，避免把登录页访问误算为登录成功
• setUser 应在获取到稳定用户 ID 后调用；未登录用户仍会通过 sessionId 统计会话和页面数据

如果行为事件用于精确计数，behaviorSampleRate 应保持为 1。生产环境可单独降低异常事件的 sampleRate。

后续规划

• sourcemap 上传与反解
• 白屏检测
• Web Vitals 指标
• 动态采样配置
• 小程序 SDK
• Hybrid/WebView 容器信息采集
• traceId 链路打通

0.2.7 接口请求统计

新增 api_request 事件，记录成功、HTTP 错误、业务错误、网络错误、超时、取消和排除请求。Fetch/XHR 的原始返回值和错误仍交给业务代码处理。

• trackApiRequests：默认 true，可关闭请求指标采集。
• apiSampleRate：默认 1，成功和失败请求使用同一采样率，与异常 sampleRate 独立。
• 接口地址不含查询参数和片段，指标不包含操作轨迹。失败请求在同一条指标中附带业务码、错误信息、查询参数、请求正文和响应正文，使用原有的脱敏和大小限制；成功、取消及排除请求不保存正文。监控平台可按单条请求查看详情，旧版本未采集的内容无法补回。
• 监控上报接口自身不参与统计，业务码 600 作为排除请求计数，不生成异常。
• 需要先部署支持该事件的 BFF，再发布本 SDK、更新消费应用的依赖与锁文件。已有发布版本不会自动获得新能力。