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 等资源加载失败
• 自动监控 fetch 请求失败、HTTP 状态失败和业务响应码失败
• 自动监控 XMLHttpRequest 请求失败、HTTP 状态失败和业务响应码失败
• 默认将响应 JSON 中 code 不为数字或字符串 200 的请求记录为 api_error
• 接口异常只提取业务码和错误消息，不保存完整响应体
• 自动记录点击行为 breadcrumbs
• 自动上报首次页面访问和 SPA 路由切换
• 自动上报页面可见停留时长
• 自动上报点击事件，忽略输入框和文本域的输入内容
• 默认不采集点击元素文本，只有显式设置 captureClickText: true 才采集
• 默认移除URL账号、查询参数及非路由hash，避免泄露token等敏感信息
• 支持 trackLogin 记录登录次数
• 支持 captureEvent('business', ...) 上报业务自定义事件
• 自动携带浏览器、系统、设备类型和网络类型
• 自动采集基础 navigation timing
• 支持 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 链路打通