@ bernierllc/ 拖放器
生产准备结构化伐木,具有多路运输,日志水平,关联跟踪,伯尼环礁生态系统性能监测.
特征
- 结构化日志:基于 JSON 的结构化日志输出与元数据
- 多重运输: 控制台、文件、HTTP、数据库和自定义运输
- 日志级别:可配置的日志水平,并带有过滤(ERROR、WARN、INFO、HTTP、VERBOSE、DEBUG、SILLY)
- 跟踪: 请求/跟踪 ID 互联互通
- 业绩跟踪: 时间跟踪、定时和剖面分析
- 数据保密: 自动 PII 保护和敏感数据掩码
- 内容管理: 丰富的上下文和元数据支持
- 儿童伐木者: 背景记录继承
- Graceful 错误处理: 运输故障恢复和错误回调
安装
npm install @bernierllc/logger
快速启动
import { Logger, LogLevel, ConsoleTransport, FileTransport } from '@bernierllc/logger';
const logger = new Logger({
level: LogLevel.INFO,
context: {
service: 'user-service',
version: '1.0.0',
environment: process.env.NODE_ENV || 'development'
},
transports: [
new ConsoleTransport({ level: LogLevel.DEBUG }),
new FileTransport({
filename: 'app.log',
level: LogLevel.INFO
})
],
sanitize: true,
enableCorrelation: true
});
logger.info('Application started');
logger.error('Database connection failed', new Error('Connection timeout'));
用法实例
基本日志
import { createLogger } from '@bernierllc/logger';
const logger = createLogger({
context: {
service: 'my-service',
version: '1.0.0',
environment: 'production'
}
});
logger.info('User logged in', { userId: '123', email: '[email protected]' });
logger.warn('High memory usage', { memoryUsage: '85%' });
logger.error('Payment failed', new Error('Invalid card'));
业绩跟踪
// Using timers
const timer = logger.startTimer('database-query');
await performDatabaseQuery();
timer.end('Query completed successfully');
// Using time wrapper
const result = await logger.time('cache-operation', async () => {
return await cacheData(key, value);
});
// Using profiling
logger.profile('data-processing');
await processLargeDataset();
logger.profile('data-processing'); // Logs duration
跟踪
import { Correlation, CorrelationManager } from '@bernierllc/logger';
// Express middleware
app.use((req, res, next) => {
const manager = CorrelationManager.getInstance();
const context = manager.fromHeaders(req.headers);
Correlation.run(context, () => {
req.logger = logger.child({
requestId: context.correlationId,
method: req.method,
url: req.url
});
next();
});
});
// In route handlers
app.get('/users/:id', async (req, res) => {
req.logger.info('Fetching user', { userId: req.params.id });
// All logs will include correlation ID automatically
});
儿童伐木者
const parentLogger = logger.child({
component: 'auth-service'
});
const childLogger = parentLogger.child({
subcomponent: 'token-validator'
});
childLogger.info('Token validated');
// Includes both component and subcomponent in context
数据保密
const logger = new Logger({
sanitize: true,
sanitizeFields: ['password', 'token', 'creditCard', 'ssn'],
transports: [new ConsoleTransport()]
});
logger.info('User data', {
username: '[email protected]',
password: 'secret123', // Will be [REDACTED]
age: 30 // Will be preserved
});
自定义运输
class SlackTransport implements LogTransport {
name = 'slack';
level = LogLevel.ERROR;
async write(entry: LogEntry): Promise<void> {
if (entry.level <= LogLevel.ERROR) {
await this.sendToSlack(entry.message, entry.metadata);
}
}
private async sendToSlack(message: string, metadata: any) {
// Send to Slack webhook
}
}
const logger = new Logger({
transports: [
new ConsoleTransport(),
new SlackTransport()
]
});
多重运输
const logger = new Logger({
level: LogLevel.INFO,
transports: [
new ConsoleTransport({
level: LogLevel.DEBUG,
formatter: new TextFormatter()
}),
new FileTransport({
filename: 'app.log',
level: LogLevel.INFO,
maxSize: 10 * 1024 * 1024, // 10MB
maxFiles: 5
}),
new HTTPTransport({
url: 'https://logs.example.com/api',
level: LogLevel.WARN,
headers: { 'Authorization': 'Bearer token' },
batchSize: 100
})
]
});
API 参考
锁定器
构造器
new Logger(options: LoggerOptions)
方法
info(message: string, metadata?: object)- 日志信息消息warn(message: string, metadata?: object)- 日志警告信息error(message: string, error?: Error, metadata?: object)- 日志错误消息debug(message: string, metadata?: object)- 日志调试消息verbose(message: string, metadata?: object)- 日志动词信息silly(message: string, metadata?: object)- 记录愚蠢的消息startTimer(label: string): LogTimer- 启动性能定时器time(label: string, fn: () => Promise<T>): Promise<T>- 时间同步操作profile(label: string)- 配置代码部分child(context: Partial<LogContext>): Logger- 创建儿童记录器setCorrelationId(id: string)- 设定相关标识setUserId(id: string)- 设定用户标识flush(): Promise<void>- 冲出所有的运输工具close(): Promise<void>- 关闭伐木机和运输工具
日志级别
enum LogLevel {
ERROR = 0, // Highest priority
WARN = 1,
INFO = 2,
HTTP = 3,
VERBOSE = 4,
DEBUG = 5,
SILLY = 6 // Lowest priority
}
运输
控制台运输
使用适当的控制台方法(错误、警告、日志、调试)控制台的日志.
文件传输
带有旋转支持的文件日志 .
HTTP 运输
向 HTTP 端点发送日志,并带有分批和重试逻辑.
数据库运输
将日志存储在连接集合的数据库中 .
格式化器
JSON 主题
产出结构化的JSON日志.
文本格式
产出人可读文本日志.
结构d 格式
产出平整结构日志并有前缀字段.
运行时配置
日志员通过配置文件支持运行时间配置,允许您自定义日志行为而不修改代码.
快速设置
-
初始化配置 :
npm run config:init -
编辑生成的
logger.config.js数字 :module.exports = { level: 'info', context: { service: 'my-service', version: '1.0.0' }, console: { enabled: true, level: 'debug' } }; -
在代码中使用 :
import { createLoggerFromConfig } from '@bernierllc/logger'; const logger = await createLoggerFromConfig(); logger.info('Application started');
配置发现
记录器在此顺序下自动发现配置文件 :
logger.config.js(JavaScript - 建议)logger.config.cjs(共同JS) (中文(简体) )logger.config.mjs(ES模块)logger.config.json(杰森语)package.json→"logger"键
CLI 命令
# Initialize configuration
npm run config:init
# Validate configuration
npm run config:validate
# Print resolved configuration
npm run config:print
环境变量
所有配置选项都可以被覆盖 LOGGER_* 环境变量:
LOGGER_LEVEL=debug
LOGGER_SERVICE=my-service
LOGGER_CONSOLE_LEVEL=info
LOGGER_FILE_ENABLED=true
LOGGER_FILE_FILENAME=logs/app.log
完整文档
详细的配置选项、实例和迁移指南见: Logger 运行时配置文档
配置
锁定选项
interface LoggerOptions {
level: LogLevel; // Minimum log level
transports: LogTransport[]; // Array of transports
context?: Partial<LogContext>; // Default context
enableCorrelation?: boolean; // Enable correlation tracking
sanitize?: boolean; // Enable data sanitization
sanitizeFields?: string[]; // Fields to sanitize
formatter?: LogFormatter; // Default formatter
onError?: (error: Error, transport: string) => void; // Error handler
}
日志语句
interface LogContext {
service: string; // Service name
version: string; // Service version
environment: string; // Environment (dev, staging, prod)
hostname?: string; // Server hostname
pid?: number; // Process ID
thread?: string; // Thread identifier
[key: string]: any; // Additional context fields
}
处理错误
日志包括全面处理错误:
const logger = new Logger({
transports: [transport1, transport2],
onError: (error, transportName) => {
console.error(`Transport ${transportName} failed:`, error);
// Handle transport failures (e.g., fallback logging)
}
});
运输故障是孤立的,不影响其他运输或应用执行.
业绩
该伐木机被优化用于生产:
- 最小伐木量(每个伐木条目小于1ms)
- 同步传输写入
- 限制有效消息和元数据大小
- 网络运输的智能分批
- 记忆意识关联跟踪
最佳做法
- 使用适当的日志级别 - 实际出错准备金
- 包含上下文 - 在日志条目中添加相关的元数据
- 使用关联ID - 跟踪各种服务的要求
- 敏感数据的保密 - 防止PII泄漏
- 适当配置运输工具 - 不同产出的不同水平
- 使用儿童记录器 - 创建针对上下文的日志
- 处理运输故障 - 执行错误回调
- 监测业绩 - 使用内置计时功能
一体化状况
锁定集成
- 状态: N/A - 这是核心日志包
- 使用量: 其他 BernerLLC 包与这个日志集成,用于整个生态系统的一致记录
Docs- 成套集成软件
- 状态: 准备 - 全类型文件导出支持
- 格式: 包含综合API文档的TypeDoc
- 特征: 自动文档生成、代码示例和类型定义
NeverHub 整合
- 状态: 综合 - 全面服务发现和事件总线支持
- 执行情况数字 :
- 运行时自动检测 NeverHub 可用性
- 无法使用 NeverHub 时的分级
- 在NeverHub存在时增强运输能力
- 有伐木能力的服务登记
- 事件驱动日志汇总和转发
- 能力数字 :
- NeverHub 配置服务的动态配置
- 利用分布式追踪增强可观察性
- 通过日志自动报告服务健康情况
- 跨服务日志关联
发展
# Install dependencies
npm install
# Build the package
npm run build
# Run tests
npm test
# Run tests with coverage
npm run test:coverage
# Lint code
npm run lint
移徙:Zod 4(破碎)
此放出会将软件包移动到 zod 4 (zod@^4.6.7)来修复zod 3.x咨询. 导出配置方案( E)loggerConfigSchema, (中文(简体) ), resolvedLoggerConfigSchema)现在为zod 4类型. 仍在Zod 3上的消费者必须升级为Zod 4来组成这些出口.
许可证
版权(c)2025 Bernier有限责任公司。 版权所有.
相关软件包
- @bernierllc/retry-policy (英语) - 用于运输重试逻辑
- @bernierllc/csv-parser (英语) - 可用此日志调试
- @bernierllc/电子邮件发送器 - 可能使用这个记录器进行操作跟踪