@multi-agent/logger

轻量级 Node.js 日志库，支持 TraceId 链路追踪。

特性

• 双重输出 - 终端彩色显示 + JSONL 文件持久化
• TraceId 追踪 - 内置链路追踪支持
• AsyncLocalStorage - 自动传递上下文
• 子 Logger - 模块化日志标识
• 零配置 - 开箱即用

安装

npm install @multi-agent/logger
# or
bun add @multi-agent/logger

快速开始

import { createLogger } from '@multi-agent/logger'

const logger = createLogger({
  name: 'my-app',
  logDir: './logs',
  level: 'info'
})

logger.info('Hello world')
logger.info('With data', { userId: '123' })
logger.warn('Warning message')
logger.error('Error occurred', { error: 'details' })

TraceId 链路追踪

import { createLogger, withTrace, generateTraceId } from '@multi-agent/logger'

const logger = createLogger({ name: 'my-app' })

// 方式1: 显式传递 traceId
const traceId = generateTraceId()
logger.info('处理请求', { traceId, step: 1 })
logger.info('请求完成', { traceId, step: 2 })

// 方式2: AsyncLocalStorage 自动传递
await withTrace(traceId, async () => {
  logger.info('开始处理')  // 自动带上 traceId
  await doSomething()
  logger.info('处理完成')  // 同样带上 traceId
})

子 Logger

const logger = createLogger({ name: 'my-app' })
const dbLogger = logger.child('db')
const httpLogger = logger.child('http')

dbLogger.info('Query executed')   // [my-app:db] Query executed
httpLogger.info('Request received') // [my-app:http] Request received

API

createLogger(options)

interface LoggerOptions {
  name: string        // 应用名称
  logDir?: string     // 日志目录，默认 './logs'
  level?: LogLevel    // 最低日志级别，默认 'info'
}

type LogLevel = 'debug' | 'info' | 'warn' | 'error'

Logger 方法

logger.debug(msg: string, data?: object)
logger.info(msg: string, data?: object)
logger.warn(msg: string, data?: object)
logger.error(msg: string, data?: object)
logger.child(module: string): Logger

Trace API

generateTraceId(): string   // 生成 traceId (tr_xxx)
generateSpanId(): string    // 生成 spanId (sp_xxx)
getTraceId(): string | undefined
withTrace<T>(traceId: string, fn: () => T | Promise<T>): T | Promise<T>

输出格式

终端（彩色）

[2025-12-21 10:30:45] [INFO ] [my-app] [tr_xxx] 收到请求 {"userId":"123"}

JSONL 文件

{"ts":"2025-12-21T10:30:45.123Z","level":"info","agent":"my-app","traceId":"tr_xxx","msg":"收到请求","data":{"userId":"123"}}

文件位置: {logDir}/{name}.jsonl