@seeklane/log-monitor

@log-monitor/sdk

自建前端监控 SDK（fundebug 兼容 API）：JS runtime / 资源加载 / HTTP 请求 / Vue3 错误采集 + 行为面包屑。TypeScript strict 编写，零运行时依赖（vue 仅为可选 peer，仅类型引用）。

安装与接入

npm install @log-monitor/sdk

import { init } from '@log-monitor/sdk';

init({
  apiKey: '你的项目 apiKey', // 必填，在 Admin 后台创建项目后获取
  appversion: '1.2.0',      // 可选：版本标识（对齐 fundebug.appversion）
  releasestage: 'production', // 可选：production / test / development
  metadata: { userId: 42 },   // 可选：随事件上报的自定义元数据
});

API（对标 fundebug）

init(options)

可重复调用 init，后一次配置覆盖前一次；不会重复安装监听或包装（幂等）。

notifyError(err, extra?) / notify(message, extra?)

import { notifyError, notify } from '@log-monitor/sdk';

try {
  riskyOperation();
} catch (err) {
  notifyError(err as Error, { scene: 'checkout', orderId: '123' }); // kind = 'runtime'
}

notify('支付流程完成'); // kind = 'message'

Vue3 接入（对标 fundebug-vue）

import { createApp } from 'vue';
import { init } from '@log-monitor/sdk';
import { LogMonitorVue } from '@log-monitor/sdk/vue';

const app = createApp(App);
init({ apiKey: 'xxx' });
app.use(new LogMonitorVue());

内部注册 app.config.errorHandler：错误以 kind='vue' 上报，extra 携带 lifecycleHook（如 setup）与 componentChain（沿 $parent 向上收集组件名，最多 10 层）。若宿主已设置 errorHandler，会先调用原处理器，再上报（不丢失原有逻辑）。

采集范围

• runtime：window.addEventListener('error', handler, true) 捕获的 JS 错误
• resource：error 事件 target 为元素时的资源加载错误（受 silentResource 控制）
• unhandledrejection：Promise 未处理拒绝（Error 取堆栈，其它取字符串）
• http：包装 window.fetch 与 XMLHttpRequest，状态 ≥400 或网络异常上报（受 silentHttp 控制）
• vue：Vue3 errorHandler 捕获的错误

面包屑与隐私

• 类型：console（error/warn）、click（CSS 选择器路径）、navigation（pushState/replaceState/popstate/hashchange）、network（method/url/status）
• 面包屑随错误一起上报，上报后从缓冲移除
• 隐私要求：绝不采集 input/textarea/select 的值，HTTP 面包屑不含请求体
• SDK 向自身 dsn 发送的上报请求不会被重复采集（防自激循环）

上报与重试

• 队列满 10 条或每 5s 批量上报：POST {dsn}，body 为 { apiKey, event } JSON
• visibilitychange → hidden 与 pagehide 时改用 navigator.sendBeacon（Blob type text/plain），不可用时降级 fetch keepalive
• 网络失败 / 429 / 5xx：写入 localStorage（键 log_monitor_queue，上限 50 条 FIFO），下次 init 时重发并清空；其它 4xx 不重试
• deviceId 持久于 localStorage(log_monitor_device_id)，session 持久于 sessionStorage(log_monitor_session)
• SDK 所有逻辑 try/catch 包裹，绝不向宿主抛错

构建产物

dist/
├── index.js          # ESM（主入口）
├── shared.js         # core 唯一副本（rollup 共享 chunk，index.js / vue.js 均引用）
├── index.umd.cjs     # UMD，全局名 LogMonitorSDK
├── vue.js            # ESM（Vue3 插件入口，薄插件，import './shared.js'）
├── vue.umd.cjs       # UMD，全局名 LogMonitorVue
└── types/            # d.ts（dist/types/index.d.ts、dist/types/vue/index.d.ts）

构建目标 ES2020；vue 为外部依赖（ESM import / UMD 全局 Vue）。

本地开发

npm run type-check   # tsc --noEmit
npm test             # vitest run（jsdom 环境）
npm run build        # vite build（两次单入口构建：index + vue）