@ guiai/ logg
还有一个简单、几乎零依赖性的结构日志遵守记录器实施.
特征
- 🛠️ 堆叠解析: 自动抓取并包含用于加强调试的堆栈跟踪信息
- 📞 呼叫记录: 提供有关调用函数的详细信息, 并使用可点击超链接的文件
- 🗄️ JSON 格式和 stdout 格式: 以 JSON 格式输出日志, 以便于解析并与日志管理工具集成
- 🎨 漂亮格式: 在浏览器控制台支持下开发的美丽彩色输出
- 🔄 滴入替换: 可作为温斯顿等受欢迎的伐木工的直接替代品
- 📏 最佳做法:实施结构化伐木行业最佳做法
- 🧩 直观 API: 简单而易于使用的流利的API 快速集成
- 🌐 通用: 在节点和浏览器环境中工作
- ⚡ 0 配置: 以合理的默认值在框外工作
预览
安装
npm install @guiiai/logg
代理技能
安装 日志技能 给您的 AI 编码代理 :
npx skills add guiiai/logg
快速启动
import { initLogger, useGlobalLogger } from '@guiiai/logg'
// Initialize with defaults (Verbose level, Pretty format)
initLogger()
// Create a logger and start logging
const log = useGlobalLogger('MyApp')
log.log('Hello world!')
用法实例
基本用途
import { createLogg, Format, LogLevel, setGlobalFormat, setGlobalLogLevel } from '@guiiai/logg'
setGlobalLogLevel(LogLevel.Debug)
setGlobalFormat(Format.Pretty) // Otherwise it will output JSON
// Create a logger instance with a specific context
const log = createLogg('http/request').useGlobalConfig()
// Log messages with different levels
log.debug('Debugging info')
log.log('Regular log')
log.warn('Warning message')
log.error('Error occurred')
添加自定义字段
// Add single field
log
.withField('requestId', req.id)
.withField('url', req.url)
.error('Resource not found (404)')
// Add multiple fields at once
log
.withFields({
userId: '12345',
ip: '192.168.1.1',
userAgent: 'Mozilla/5.0'
})
.log('User logged in')
处理错误
try {
// Some operation
}
catch (err) {
// Automatically extracts error message, stack trace, and cause
log.withError(err).error('Operation failed')
// Or use errorWithError for more control
log.errorWithError('Failed to process request', err)
}
儿童伐木者
const parentLog = createLogg('app').useGlobalConfig()
// Create child logger with persistent fields
const childLog = parentLog.child({
module: 'database',
version: '1.0.0'
})
// All logs from childLog will include the parent fields
childLog.log('Connected to database')
自动文本记录器
import { createLogger } from '@guiiai/logg'
// Automatically includes file path and line number with clickable hyperlinks
const log = createLogger().useGlobalConfig()
log.log('This log knows where it came from!')
自定义时间格式
const log = createLogg('app')
.useGlobalConfig()
.withTimeFormatter((date) => {
return date.toLocaleString('en-US', {
timeZone: 'America/New_York'
})
})
log.log('Log with custom timestamp')
处理错误
// Transform errors before logging
const log = createLogg('app')
.useGlobalConfig()
.withErrorProcessor((err) => {
if (err instanceof CustomError) {
// Add custom properties or transform the error
return { ...err, customField: 'value' }
}
return err
})
log.withError(someError).error('Processed error')
API 参考
Logger 工厂函数
createLogg(context: string): Logg
创建一个带有指定上下文的新日志实例.
const log = createLogg('MyModule')
createLogger(context?: string): Logg
从呼叫站点(文件路径和行号)创建自动上下文的日志。 在支持的终端中包括可点击的超链接.
const log = createLogger() // Context is auto-generated
const log2 = createLogger('CustomContext') // Override with custom context
createGlobalLogger(context?: string): Logg
创建自动上下文的日志并应用全局配置.
const log = createGlobalLogger()
initLogger(level?: LogLevel, format?: Format): void
初始化默认的全局日志配置 .
import { Format, initLogger, LogLevel } from '@guiiai/logg'
initLogger(LogLevel.Verbose, Format.Pretty)
别名 :
useLogg→createLogguseLogger→createLoggeruseGlobalLogger→createGlobalLogger
伐木实例方法
配置方法
useGlobalConfig(): Logg- 对日志实例应用全局配置child(fields?: Record<string, any>): Logg- 创建一个带有额外持久字段的儿童记录器withContext(context: string): Logg- 动态设置上下文(返回克隆实例)withLogLevel(logLevel: LogLevel): Logg- 动态设置日志级别(返回克隆实例)withLogLevelString(logLevelString: LogLevelString): Logg- 使用字符串设置日志级别(返回克隆实例)withFormat(format: Format): Logg- 动态设定输出格式(返回克隆实例)withFields(fields: Record<string, any>): Logg- 别提了child()withField(key: string, value: any): Logg- 添加一个自定义字段withError(err: Error | unknown): Logg- 附加自动提取信件、堆栈和原因的错误对象withCallStack(errorLike: { message: string, stack?: string }): Logg- 添加调用堆栈信息withTimeFormatter(fn: (date: Date) => string): Logg- 为物质函数设定自定义时间withErrorProcessor(fn: (err: Error | unknown) => Error | unknown): Logg- 设置自定义错误处理器功能
记录方法
debug(message: any, ...optionalParams: any[]): void- 日志调试级消息verbose(message: any, ...optionalParams: any[]): void- 日志动词级消息log(message: any, ...optionalParams: any[]): void- 日志信息级消息warn(message: any, ...optionalParams: any[]): void- 日志警告级消息error(message: any, stack?: string, ...optionalParams: any[]): void- 日志错误级别消息errorWithError(message: any, err: Error | unknown, ...optionalParams: any[]): void- 自动取出错误的日志错误
全局配置
日志级别
import { getGlobalLogLevel, getGlobalLogLevelString, LogLevel, setGlobalLogLevel, setGlobalLogLevelString } from '@guiiai/logg'
setGlobalLogLevel(LogLevel.Debug)
const level = getGlobalLogLevel()
// Or use string-based methods
setGlobalLogLevelString('debug')
const levelString = getGlobalLogLevelString()
格式
import { Format, getGlobalFormat, setGlobalFormat } from '@guiiai/logg'
setGlobalFormat(Format.Pretty)
const format = getGlobalFormat()
时间主题
import { getGlobalTimeFormatter, setGlobalTimeFormatter } from '@guiiai/logg'
setGlobalTimeFormatter(date => date.toISOString())
const formatter = getGlobalTimeFormatter()
数字和类型
LogLevel
enum LogLevel {
Error = 0,
Warning = 1,
Log = 2,
Verbose = 3,
Debug = 4
}
LogLevelString
type LogLevelString = 'error' | 'warn' | 'log' | 'verbose' | 'debug'
Format
enum Format {
JSON = 'json',
Pretty = 'pretty'
}
配置
日志级别
日志级别控制哪个消息是输出 。 较高级别包括所有较低级别.
| 职等 | 数值 | 说明 |
|---|---|---|
| 错误 | 0 个 | 只有错误消息 |
| 3⁄4 ̄ ̧漯B | 1个 | 错误和警告 |
| 日志 | 2个 | 错误、警告和一般日志 |
| 声波 | 3个 | 所有以上加动词信息 |
| 调试 | 页:1 | 包括调试信息在内的所有信件 |
输出格式
JSON 格式
结构化的JSON输出,理想的生产环境和日志汇总工具.
{ "level": "log", "context": "app", "timestamp": "2024-01-01T00:00:00.000Z", "message": "User logged in", "fields": { "userId": "123" } }
漂亮格式
人可读取的有色产出促进发展. 自动检测浏览器环境并相应调整输出.
[2024-01-01 00:00:00] LOG app: User logged in { userId: '123' }
环境支助
节点.js
全力支持所有特征,包括:
- 终端超链接( VS 代码, iTerm2等)
- 彩色输出
- 堆栈跟踪解析
浏览器
优化浏览器支持方式 :
- 方便主机输出
- 在浏览器演示工具中适当扩展对象
- 自动格式检测
为什么?
- 轻巧: 最小的依赖性( 只有3 个运行时的隔间)
- 类型安全: 包含完整类型定义的完整类型脚本支持
- 弹性: 在任何环境中进行没有配置的工作
- 方便开发者: 美丽的输出和可点击的源链接
- 生产准备: 用于日志汇总系统的 JSON 输出