@zhaogyna/core

Monitor SDK 的核心逻辑层，提供 Client、Scope、Session、Tracing、全局 API 等。不依赖任何平台 API（浏览器 / Node），可跨环境复用。

安装

npm install @zhaogyna/core

本包为内部依赖层，终端用户通常无需单独安装。框架包已自动包含。

导出 API

初始化与客户端

import { init, setClient, bindClient, getClient, isInitialized } from '@zhaogyna/core'

init(options)            // 初始化 SDK（创建 BrowserClient 并设为全局）
setClient(client)        // 手动设置全局 Client
bindClient(client)       // 设置 Client 并触发 afterInit 生命周期
getClient()              // 获取当前全局 Client
isInitialized()          // 检查 SDK 是否已初始化

事件上报

import { captureException, captureMessage, track } from '@zhaogyna/core'

// 捕获异常
captureException(new Error('something broke'))

// 捕获异常 + 一次性 Scope
captureException(err, (scope) => {
  scope.setTag('section', 'payment')
  scope.setExtra('orderId', 'ORD-123')
})

// 捕获消息
captureMessage('Something happened', 'warning')

// 自定义埋点
track('purchase_complete', { product: 'iPhone', price: 999 })

captureException 支持：

• Error.cause 链递归解析（最深 5 层）
• AggregateError 扁平展开所有错误
• Track 事件自动检查 trackSampleRate、限制属性数量、stripTrackKeys 脱敏、beforeTrack 钩子、自动添加面包屑

上下文 API

import {
  setUser, setTag, setTags, setExtra, setExtras,
  setLevel, setTransaction, setFingerprint,
  addBreadcrumb, clearBreadcrumbs,
} from '@zhaogyna/core'

setUser({ id: 'user-123', email: '[email protected]', username: 'john' })
setTag('feature', 'checkout')
setTags({ env: 'prod', region: 'cn-north' })
setExtra('cartSize', 5)
setExtras({ plan: 'premium', trial: false })
setLevel('warning')
setTransaction('CheckoutFlow')
setFingerprint(['my-error-group'])
addBreadcrumb({ category: 'ui', message: 'Clicked checkout', level: 'info', timestamp: Date.now() })
clearBreadcrumbs()

分布式追踪

import { startSpan } from '@zhaogyna/core'

const span = startSpan('api/fetch-orders')
try {
  const orders = await fetchOrders()
  span.setStatus('ok')
  span.setData('orderCount', orders.length)
} catch (err) {
  span.setStatus('internal_error')
  captureException(err)
} finally {
  span.finish()
}

startSpan(name, options?) 返回 SpanHandle：

• setStatus(status) — 设置状态（ok / internal_error / ...）
• setData(key, value) — 附加数据
• finish() — 结束 Span

漏斗分析

import { startFunnel, trackFunnelStep, endFunnel } from '@zhaogyna/core'

startFunnel('checkout_funnel')
trackFunnelStep('checkout_funnel', 'view_cart', { itemCount: 3 })
trackFunnelStep('checkout_funnel', 'enter_payment', { method: 'alipay' })
trackFunnelStep('checkout_funnel', 'complete_payment', { amount: 999 })
endFunnel('checkout_funnel')

作用域隔离

import { withScope } from '@zhaogyna/core'

withScope((scope) => {
  scope.setTag('temp', 'value')
  captureException(err)  // 只附加到本次上报，不影响全局 Scope
})

多实例 / 微前端

import { createClient, getActiveClients, registerClient, unregisterClient, findClientForUrl } from '@zhaogyna/core'

// 创建隔离实例（不设为全局）
const client = createClient({ dsn: '...', release: '[email protected]' })

// 多实例管理
const clients = getActiveClients()
const matched = findClientForUrl('/sub-app/dashboard')
registerClient(client)
unregisterClient(client)

生命周期

import { on, flush, close } from '@zhaogyna/core'

// 监听生命周期事件
const unsubscribe = on('beforeFlush', (event) => console.log('flush:', event))
on('afterInit', () => console.log('SDK initialized'))

flush()      // 手动刷新发送队列
close()      // 关闭 SDK

unsubscribe()  // 取消订阅

可用事件：beforeInit、afterInit、beforeClose、afterClose、beforeFlush

集成管理

import { addIntegration, lazyLoadIntegration } from '@zhaogyna/core'

// 运行时动态添加集成
addIntegration(someIntegration())

// 按需加载集成（减小初始包体积）
const replay = lazyLoadIntegration(
  () => import('@zhaogyna/browser/sessionReplay'),
  'sessionReplay'
)
addIntegration(replay)

BaseClient

抽象基类，供平台层（BrowserClient）继承。事件处理管线：

1. 服务端限流检查（x-monitor-rate-limits）
2. 确定性采样决策（sampleDecision）
3. Scope 合并（?? 合并，避免 falsy 值覆盖）
4. 事件处理器（Client + Scope 上的 event processors）
5. 集成 preprocessEvent 钩子
6. 集成 processEvent 钩子
7. beforeSend / beforeSendTransaction 回调
8. 序列化（normalize）
9. 发送队列

事件处理细节

• Fingerprint 模板变量：{{ default }}、{{ transaction }}、{{ error.message }}、{{ error.type }}、{{ error.module }}
• URL 脱敏：stripUrlParams 贯穿事件、面包屑和堆栈帧
• ClientReport：30s 定时器，上报丢弃事件统计
• Session：通过 StorageAdapter 抽象注入（平台层实现），支持崩溃检测、bfcache 恢复、crashed 终态、最大 3600s 时长、设备 ID 365 天持久化

License

MIT