@composy/logger-core
v0.0.2
Published
Framework-agnostic logger core for LDesign
Maintainers
Readme
@composy/logger-core
@composy/logger-core
提供 LDesign 的框架无关日志能力,适合作为应用、库、CLI 或 engine 插件的底层日志运行时。
能力范围
- 分级日志:
trace / debug / info / warn / error / fatal - 统一日志管线:插件前置处理、过滤、历史缓冲、监听器、同步或异步传输
- 可扩展传输器:
console、storage、http、websocket、dev-bridge - 错误追踪:
window.onerror、unhandledrejection、资源加载错误、可选控制台错误捕获 - 性能监控:计时器、长任务监控、指标采样
- Engine 接入:可直接注册到
packages/engine的插件体系
目录约定
src
├─ engine # Engine 插件与状态键(framework-agnostic)
├─ errors # 错误追踪与面包屑管理
├─ formatters # 日志输出格式化
├─ logger # Logger 核心实现与工厂函数
├─ performance # 性能监控与指标收集
├─ plugins # Logger 插件(控制台拦截、性能监控)
├─ styles # 控制台输出样式(主题、颜色、徽章)
├─ transports # 日志传输器(控制台、HTTP、WebSocket、存储、开发桥接)
├─ types # 核心类型定义(LogLevel、LogEntry、LogTransport 等)
└─ utils # 通用工具函数(队列、缓冲区、对象池、压缩、脱敏等)包结构原则
logger是唯一的日志写入核心实现,其他框架适配包不能复制写入管线engine/runtime.ts负责 engine API 注册、状态同步和状态清理,Vue 等适配层必须复用这些 helperutils/environment.ts负责运行环境探测,运行时代码不直接读取 Node.js 全局processerrors/stack-parser.ts使用线性字符串解析,避免复杂正则在异常堆栈上产生回溯风险
类型安全
本包 零 any 类型,所有接口和函数均使用完整 TypeScript 类型定义。核心类型包括:
LogLevel— 日志级别枚举(TRACE=0 到 FATAL=50)LogEntry— 完整日志条目接口,包含 id、时间戳、级别、消息、数据、错误、标签、上下文等字段LogTransport— 传输器抽象接口,支持 write/writeBatch/flush/closeLoggerPlugin— 插件抽象接口,支持 install/init/destroy/beforeLog/afterLog/onError 钩子ILogger— 日志器核心 API 接口,定义所有公共方法的完整类型
快速开始
import {
createConsoleTransport,
createHttpTransport,
createLogger,
LogLevel,
} from '@composy/logger-core'
const logger = createLogger({
name: 'app',
level: LogLevel.INFO,
async: true,
transports: [
createConsoleTransport({ level: LogLevel.DEBUG }),
createHttpTransport({
url: '/api/logs',
level: LogLevel.WARN,
batchSize: 20,
batchInterval: 3000,
}),
],
})
logger.info('application started')
logger.error('request failed', new Error('network error'))
await logger.flush()插件与扩展
import { createConsolePlugin, createLogger } from '@composy/logger-core'
const logger = createLogger({ name: 'app' })
logger.use(
createConsolePlugin({
interceptWarn: true,
interceptError: true,
})
)Engine 用法
import { createLoggerEnginePlugin } from '@composy/logger-core/engine'
engine.use(
createLoggerEnginePlugin({
name: 'logger',
level: 20,
registerApi: true,
})
)如果 engine 外部已经有 logger 实例,可以直接注入并避免卸载时销毁:
import { createLogger, createLoggerEnginePlugin } from '@composy/logger-core'
const logger = createLogger({ name: 'shared-runtime' })
engine.use(
createLoggerEnginePlugin({
logger,
destroyOnUnmount: false,
})
)安装后可通过 engine state 读取:
logger:instancelogger:config
也可以复用底层桥接函数:
import {
clearLoggerEngineState,
registerLoggerEngineApi,
syncLoggerEngineState,
} from '@composy/logger-core/engine'
syncLoggerEngineState(engine, logger, { name: 'logger' })
registerLoggerEngineApi(engine, 'logger', '1.0.0', logger)
clearLoggerEngineState(engine)模块详解
Logger 核心(logger/)
Logger类实现完整的ILogger接口,统一管理插件、过滤器和传输链路- 支持子日志器(
child())和上下文传播(withContext()、withTags()) - 内置对象池(
ObjectPool)和环形缓冲区(CircularBuffer),减少 GC 压力 - 异步队列(
AsyncQueue)支持批量处理、自动刷新、有界死信队列和消费回调取消订阅
传输器(transports/)
- ConsoleTransport:浏览器/Node.js 控制台美化输出,支持主题切换
- HttpTransport:批量上报,支持重试、优先级排序、Beacon API、自定义请求
- WebSocketTransport:实时推送,支持自动重连、心跳保活、消息积压
- StorageTransport:持久化到 localStorage/IndexedDB/内存,支持压缩和 TTL
- DevBridgeTransport:开发模式下通过 WebSocket 连接到 launcher 工具
可靠性与隐私边界
OfflineQueue会等待 IndexedDB/localStorage 初始化,串行化持久化操作,并通过maxSize、maxRetries、retryBatchSize控制容量和重试;onOnline()返回取消订阅函数,destroy()会清理监听器和定时器。AsyncQueue.onFlush()返回 disposer;自动重试只重试失败消费者,避免其他消费者重复处理同一批日志。retryDeadLetter()会将死信重放给当前全部消费者,外部副作用应保持幂等;onDeadLetterFull()支持异步持久化,回调异常不会中断队列。sanitizeObject()支持maxDepth、maxArrayLength、循环引用和非法 Date 保护,并使用安全属性定义处理__proto__等用户输入键。ErrorTracker.captureError()接受任意未知错误值;stop()会恢复原始全局 handler,即使原值为null也不会遗留监听器。- WebSocket/HTTP/Storage 传输器的
close()可等待已有缓冲完成;WebSocket 并发close()调用共享同一个 Promise。
错误追踪(errors/)
ErrorTracker自动捕获window.onerror、unhandledrejection、资源加载错误- 全局 handler 停止时只恢复仍由当前实例安装的函数,不会覆盖宿主或其他 tracker 在运行期间替换的 handler
BreadcrumbManager记录用户操作序列,支持导航、点击、HTTP、控制台等类型stack-parser使用线性解析替代正则,安全处理 Chrome/Firefox/Safari 堆栈格式
脱敏与离线队列(utils/)
sanitizeObject()支持maxDepth与maxArrayLength,遇到循环引用、过深对象或过长数组时返回稳定占位值,避免日志数据无限递归。OfflineQueue支持maxRetries、批量入队和onOnline()取消订阅;持久化操作按顺序执行,容量淘汰与内存队列保持一致。
性能监控(performance/)
PerformanceMonitor自动收集导航计时、资源计时、长任务MetricsCollector管理计时、计数器和仪表盘指标PerformanceTimer提供精确的代码执行时间测量
性能设计
- 创建日志时先使用对象池草稿对象,再复制为稳定快照
- 历史记录与传输器都基于快照运行,避免对象复用带来的数据串改
AsyncQueue满载淘汰最旧项时移动逻辑起点并定期压缩底层数组,避免逐条搬移队列剩余内容- 异步队列与批量传输可直接等待
Promise类型传输器,便于接入远程上报 HttpTransport.close()会解绑页面生命周期监听,避免长期页面中残留 transport 实例引用WebSocketTransport.close()即使刷新或序列化失败也会释放心跳、重连定时器和异步队列
开发命令
pnpm --filter @composy/logger-core type-check
pnpm --filter @composy/logger-core lint:check
pnpm --filter @composy/logger-core build
pnpm --filter @composy/logger-core test:run构建产物
build 使用 @composy/builder,默认由 rolldown 打包。构建后的 postbuild 会校验并归一化
dist、es、esm、lib,其中 dist/index.min.js 是以 LDesignLoggerCore
为全局名生成的真实 UMD 压缩产物,不是未压缩文件的副本。
pnpm --filter @composy/logger-core build
node --experimental-strip-types scripts/index.ts workspace:check-package-outputs --cwd packages/logger --target core