koatty_logger

v2.8.1

Published

a month ago

Logger for koatty.

0High
0Medium
0Low

richenlin

web typescript framework mvc koa2 restful agile koatty_logger thinkkoa

koatty_logger

企业级日志组件，专为 koatty 框架设计，具备强大的安全防护和性能优化特性。

✨ 特性

🔒 安全特性

路径遍历防护: 防止恶意路径访问系统敏感文件
日志注入防护: 自动过滤控制字符，防止日志伪造攻击
数据脱敏: 支持敏感字段自动脱敏，保护隐私数据
输入验证: 严格验证日志路径和内容的安全性

⚡ 性能优化

异步写入: 默认采用异步日志写入，避免阻塞主线程
批量写入: 高并发场景下的批量日志写入，显著提升性能
内存管理: 智能内存清理，防止内存泄漏
递归限制: 防止深层对象导致的性能问题
高效克隆: 优化对象克隆算法，提升脱敏性能
日志轮转: 基于时间和大小的智能日志轮转

📦 安装

npm install koatty_logger

🚀 快速开始

基础使用（推荐大多数场景）

import { DefaultLogger } from 'koatty_logger';

// 🎉 开箱即用 - 零配置,立即可用
DefaultLogger.info('应用启动成功');
DefaultLogger.warn('警告信息');
DefaultLogger.error('发生错误', new Error('示例错误'));
DefaultLogger.fatal('致命错误');  // ⚡ 新增:同步写入,进程退出时不丢失

// 💡 可选：配置日志级别和文件路径
DefaultLogger.configure({
  minLevel: 'debug',
  logFilePath: './logs/app.log',
  sensFields: new Set(['password', 'token'])
});

// 💡 动态调整配置（运行时）
DefaultLogger.setMinLevel('error');  // 只记录错误
DefaultLogger.enableBuffering();     // 启用高性能缓冲模式
DefaultLogger.disableBuffering();    // 禁用缓冲,实时输出

✨ DefaultLogger 特性：

✅ 开箱即用: 零配置,直接调用即可
✅ 动态配置: 运行时可随时调整级别、路径、缓冲等
✅ 容错降级: 初始化失败自动降级到 console 输出
✅ 全局单例: 配置一次,全局生效
✅ 便捷 API: 提供丰富的便捷方法,简化使用

高级用法（多实例场景）

适用于微服务、插件系统、复杂架构等需要独立日志器的场景：

import { Logger } from 'koatty_logger';

// 创建独立的日志器实例
const auditLogger = new Logger({
  logLevel: 'info',
  logFilePath: './logs/audit.log',
  buffer: {
    enableBuffer: true,
    maxBufferSize: 500,
    flushInterval: 100
  }
});

const userServiceLogger = new Logger({
  logLevel: 'debug',
  logFilePath: './logs/user-service.log',
  sensFields: new Set(['password', 'ssn'])
});

auditLogger.info('审计日志', { action: 'login', userId: 123 });
userServiceLogger.debug('用户服务日志');

📖 使用建议：

大多数场景: 使用 DefaultLogger (简单、便捷、统一)
微服务架构: 使用 new Logger() (隔离、独立、灵活)
混合使用: 主应用用 DefaultLogger,关键模块用独立 Logger

Fatal 日志级别 (v2.7+)

解决进程退出时日志丢失问题:

// ❌ 问题: 异步日志在进程退出时会丢失
DefaultLogger.error('Critical error');
process.exit(1);  // 日志可能丢失!

// ✅ 解决方案1: 使用 fatal (同步写入)
DefaultLogger.fatal('Critical error');
process.exit(1);  // 日志已写入,不会丢失

// ✅ 解决方案2: 使用 fatalAndExit (推荐)
await DefaultLogger.fatalAndExit('Critical error', 1);

// ✅ 解决方案3: 全局异常处理
process.on('uncaughtException', async (error) => {
  await DefaultLogger.fatalAndExit('Uncaught exception', 1, error);
});

Fatal 特性:

⚡ 同步写入 - 确保日志不丢失
🎯 最高优先级 - 总是被记录
📝 双重输出 - 同时写入文件和 console
🚀 立即刷新 - 触发缓冲区刷新

详细文档: Fatal 日志级别指南

详细示例请参考：

安全配置

import { Logger } from 'koatty_logger';

const logger = new Logger({
  logLevel: 'info',
  logFilePath: './logs/app.log',
  sensFields: new Set(['password', 'token', 'secret'])
});

// 敏感数据会自动脱敏
logger.info('用户登录', {
  username: 'john',
  password: 'secret123',  // 会被脱敏为 sec***23
  email: '[email protected]'
});

高级用法

// 异步日志写入（默认行为）
// Winston本身就是异步的，koatty_logger进一步优化了异步处理
logger.info('这条日志会异步写入，不会阻塞主线程');
logger.error('错误日志也是异步的');

// 批量写入模式 vs 异步单条写入模式
const asyncLogger = new Logger({
  logLevel: 'info',
  logFilePath: './logs/async.log'
  // 默认不启用批量写入，使用异步单条写入
});

const bufferedLogger = new Logger({
  logLevel: 'info', 
  logFilePath: './logs/buffered.log',
  buffer: {
    enableBuffer: true,   // 启用缓冲
    maxBufferSize: 100,   // 缓冲区最大100条日志
    flushInterval: 1000,  // 每秒检查一次是否需要刷新
    flushOnLevel: 'error' // error级别立即刷新
  }
});

// 动态管理敏感字段
logger.setSensFields(['creditCard', 'ssn']);
logger.clearSensFields();  // 清空敏感字段
logger.resetSensFields(['newSensitiveField']);  // 重置敏感字段

// 安全的日志文件路径设置
try {
  logger.setLogFilePath('app.log');  // ✅ 安全路径
  logger.setLogFilePath('../../../etc/passwd');  // ❌ 会抛出安全异常
} catch (error) {
  console.error('路径不安全:', error.message);
}

// 高性能缓冲配置
const highPerfLogger = new Logger({
  logLevel: 'info',
  logFilePath: './logs/high-perf.log',
  buffer: {
    enableBuffer: true,   // 启用缓冲
    maxBufferSize: 100,   // 缓冲区最大100条日志
    flushInterval: 1000,  // 每秒检查一次是否需要刷新
    flushOnLevel: 'error' // error级别立即刷新
  }
});

// 缓冲控制
await highPerfLogger.flush();  // 立即异步刷新缓冲区

// 获取统计信息
const stats = highPerfLogger.getStats();
if (stats) {
  console.log('缓冲区大小:', stats.buffer.bufferSize);
  console.log('总日志数:', stats.buffer.totalLogs);
}

// 动态调整缓冲配置
highPerfLogger.configureBuffering({
  maxBufferSize: 200,   // 调整缓冲区大小
  flushInterval: 500    // 调整检查间隔
});

// 优雅关闭（确保所有日志都被写入）
process.on('SIGINT', async () => {
  console.log('正在关闭应用...');
  await highPerfLogger.flush(); // 等待所有日志写入完成
  await highPerfLogger.destroy(); // 释放所有资源
  process.exit(0);
});

// 资源清理
logger.destroy();  // 释放所有资源

🔧 API 文档

Logger 类

构造函数

new Logger(options?: LoggerOpt)

主要方法

| 方法 | 描述 | 特性 | |------|------|------| | info(...args) | 输出信息日志 | 异步写入，自动过滤注入字符 | | error(...args) | 输出错误日志 | 异步写入，自动过滤注入字符 | | debug(...args) | 输出调试日志 | 异步写入，自动过滤注入字符 | | warn(...args) | 输出警告日志 | 异步写入，自动过滤注入字符 | | setLogFilePath(path) | 设置日志文件路径 | 路径遍历防护 | | setSensFields(fields) | 设置敏感字段 | 数据脱敏 | | clearSensFields() | 清空敏感字段 | 内存清理 | | configureBuffering(config) | 配置缓冲功能 | 高并发性能优化 | | configureSampling(key, rate) | 配置采样率 | 减少高频日志 | | setMinLevel(level) | 设置最小日志级别 | 动态级别过滤 | | getStats() | 获取统计信息 | 监控日志状态 | | flush() | 立即刷新缓冲区 | 异步操作，返回Promise | | destroy() | 销毁实例 | 资源释放，异步刷新剩余日志 |

配置选项

interface LoggerOpt {
  logLevel?: 'debug' | 'info' | 'warning' | 'error';
  logFilePath?: string;  // 安全验证的日志路径
  sensFields?: Set<string>;  // 敏感字段集合
  // 增强功能配置
  buffer?: BufferConfig;  // 缓冲配置
  sampling?: SamplingConfig;  // 采样配置
  minLevel?: LogLevelType;  // 最小日志级别
}

interface BatchConfig {
  enabled?: boolean;        // 是否启用批量写入
  maxSize?: number;         // 最大缓冲区大小（条目数）
  flushInterval?: number;   // 刷新间隔检查（毫秒）
  maxWaitTime?: number;     // 最大等待时间（毫秒）
}

🛡️ 安全最佳实践

1. 路径安全

// ✅ 推荐：使用相对路径
logger.setLogFilePath('logs/app.log');

// ❌ 避免：绝对路径或路径遍历
logger.setLogFilePath('/var/log/app.log');        // 可能失败
logger.setLogFilePath('../../../sensitive.log');  // 会抛出异常

2. 敏感数据保护

// 设置敏感字段
logger.setSensFields([
  'password', 'token', 'secret', 'key',
  'creditCard', 'ssn', 'phone', 'email'
]);

// 敏感数据会自动脱敏
const userData = {
  name: 'John',
  password: 'mySecret123',  // 会显示为 myS****123
  phone: '1234567890'       // 会显示为 123***7890
};
logger.info('用户数据', userData);

3. 注入防护

日志组件会自动过滤以下危险字符：

换行符 (\n, \r)
制表符 (\t)
控制字符 (\x00-\x1f, \x7f)

4. 异步日志最佳实践

// ✅ 推荐：默认使用异步日志（无需特殊配置）
const logger = new Logger({
  logLevel: 'info',
  logFilePath: './logs/app.log'
  // 默认就是异步写入，性能最优
});

// ✅ 推荐：高并发场景使用批量写入
const highConcurrencyLogger = new Logger({
  batchConfig: {
    enabled: true,
    maxSize: 100,        // 根据应用负载调整
    flushInterval: 1000, // 平衡性能和实时性
    maxWaitTime: 3000    // 确保日志不会丢失
  }
});

// ✅ 推荐：关键操作后手动刷新批量日志
await logger.flush(); // 确保重要日志立即写入

// ✅ 推荐：优雅关闭，等待所有日志写入完成
process.on('SIGTERM', async () => {
  console.log('接收到关闭信号，正在刷新日志...');
  await logger.flush();
  logger.destroy();
  process.exit(0);
});

// ⚠️ 注意：批量模式的权衡
// 缓冲模式：更高性能，但可能延迟写入
// 配置 flushOnLevel 可以让关键日志立即写入
const logger = new Logger({
  buffer: {
    enableBuffer: true,
    flushOnLevel: 'error'  // error 级别立即刷新
  }
});
logger.error('Critical system error'); // 立即刷新

5. 批量写入最佳实践

// ✅ 推荐：应用关闭前手动刷新
process.on('SIGINT', async () => {
  await logger.flush();
  logger.destroy();
  process.exit(0);
});

// ⚠️ 注意：实时性要求高的日志可配置立即刷新
const logger = new Logger({
  buffer: {
    enableBuffer: true,
    flushOnLevel: 'error'  // error 和 warning 立即刷新
  }
});
logger.error('Critical error occurred'); // 立即写入

🚀 增强功能

koatty_logger 的 Logger 类已整合所有增强功能，无需单独使用 EnhancedLogger：

特性概览

智能缓冲: 可配置的日志缓冲机制，优化批量写入性能
日志采样: 减少高频日志数量，避免日志洪流
级别过滤: 运行时动态调整日志级别，灵活控制输出
统计监控: 实时统计日志处理情况，便于性能分析

使用增强功能

import { createLogger, Logger } from 'koatty_logger';

// 方式1: 使用工厂函数（推荐）
const logger = createLogger({
  minLevel: 'info',
  buffer: {
    enableBuffer: true,
    maxBufferSize: 100,
    flushInterval: 1000,
    flushOnLevel: 'error'
  },
  sampling: {
    sampleRates: new Map([
      ['high-frequency-api', 0.1],  // 10% 采样率
      ['debug-trace', 0.05]          // 5% 采样率
    ])
  }
});

// 方式2: 直接实例化
const enhancedLogger = new Logger({
  minLevel: 'debug',
  logFilePath: './logs/app.log',
  buffer: {
    enableBuffer: true,
    maxBufferSize: 200,
    flushInterval: 500
  }
});

缓冲配置

const logger = createLogger({
  buffer: {
    enableBuffer: true,        // 启用缓冲
    maxBufferSize: 100,        // 缓冲区最大100条
    flushInterval: 1000,       // 每秒检查一次
    flushOnLevel: 'error'      // error级别立即刷新
  }
});

// 动态调整缓冲配置
logger.configureBuffering({
  maxBufferSize: 200,
  flushInterval: 500
});

// 手动刷新缓冲区
await logger.flush();

// 获取统计信息
const stats = logger.getStats();
console.log('缓冲区大小:', stats.buffer.bufferSize);
console.log('总日志数:', stats.buffer.totalLogs);
console.log('丢弃日志数:', stats.buffer.droppedLogs);
console.log('丢弃率:', stats.buffer.droppedRate);

日志采样

const logger = createLogger({
  sampling: {
    sampleRates: new Map([
      ['api-request', 0.1],      // API请求只记录10%
      ['database-query', 0.05]   // 数据库查询只记录5%
    ])
  }
});

// 使用采样日志方法
logger.InfoSampled('api-request', 'API请求', { url: '/api/users', method: 'GET' });
logger.DebugSampled('database-query', 'SQL查询', { sql: 'SELECT * FROM users' });

// 动态调整采样率
logger.configureSampling('api-request', 0.2);  // 调整为20%

// 查看采样统计
const stats = logger.getStats();
stats.sampling?.forEach((value, key) => {
  console.log(`${key}: 采样率=${value.sampleRate}, 计数=${value.counter}`);
});

级别过滤

const logger = createLogger({
  minLevel: 'info'  // 只记录 info 及以上级别
});

// 这些日志会被过滤掉
logger.Debug('调试信息');  // ❌ 被过滤

// 这些日志会被记录
logger.Info('信息日志');   // ✅ 记录
logger.Warn('警告日志');   // ✅ 记录
logger.Error('错误日志');  // ✅ 记录

// 动态调整日志级别
logger.setLogLevel('debug');  // 现在 debug 日志也会被记录

// 查看当前级别
const stats = logger.getStats();
console.log('当前最小级别:', stats.minLevel);

综合示例

import { createLogger } from 'koatty_logger';

// 生产环境配置
const productionLogger = createLogger({
  minLevel: 'info',
  logFilePath: './logs/production.log',
  sensFields: new Set(['password', 'token', 'creditCard']),
  buffer: {
    enableBuffer: true,
    maxBufferSize: 200,
    flushInterval: 1000,
    flushOnLevel: 'error'
  },
  sampling: {
    sampleRates: new Map([
      ['http-request', 0.1],
      ['cache-hit', 0.01]
    ])
  }
});

// 普通日志
productionLogger.Info('应用启动', { port: 3000 });

// 采样日志（高频场景）
productionLogger.InfoSampled('http-request', '请求处理', {
  method: 'GET',
  url: '/api/users',
  duration: 45
});

// 自动脱敏
productionLogger.Info('用户登录', {
  username: 'john',
  password: 'secret123',  // 会被脱敏
  token: 'abc123xyz'      // 会被脱敏
});

// 获取统计信息
const stats = productionLogger.getStats();
console.log('日志统计:', {
  缓冲区: stats.buffer,
  采样: Object.fromEntries(stats.sampling || new Map()),
  级别: stats.minLevel
});

// 优雅关闭
process.on('SIGTERM', async () => {
  console.log('正在关闭应用...');
  await productionLogger.flush();
  productionLogger.stop();
  process.exit(0);
});

环境变量配置

增强日志器支持以下环境变量：

# 日志级别
export LOG_LEVEL=info            # debug | info | warn | error

# 缓冲配置
export LOG_BUFFER_SIZE=100       # 缓冲区大小
export LOG_FLUSH_INTERVAL=1000   # 刷新间隔（毫秒）
export LOG_FLUSH_ON_LEVEL=error  # 立即刷新的最低级别
export LOG_ENABLE_BUFFER=true    # 启用/禁用缓冲

# 环境配置（自动调整缓冲行为）
export NODE_ENV=development      # 开发环境：自动禁用缓冲，日志实时输出
export NODE_ENV=test             # 测试环境：自动禁用缓冲
export NODE_ENV=production       # 生产环境：启用缓冲，获得最佳性能

使用示例：

# 生产环境（启用批量写入）
NODE_ENV=production LOG_LEVEL=info npm start

# 开发环境（禁用批量写入，实时输出）
NODE_ENV=development LOG_LEVEL=debug npm run dev

# 测试环境（禁用批量写入）
NODE_ENV=test npm test

🔍 测试

# 运行所有测试
npm test

# 运行安全测试
npm test -- --testNamePattern="Security"

# 运行性能测试
npm test -- --testNamePattern="Performance"

📊 性能指标

异步写入: 相比同步写入，CPU阻塞时间减少 95%
批量写入: 高并发场景下性能提升 200-500%
- 1000条/秒：性能提升 200%
- 10000条/秒：性能提升 500%
- 缓冲区命中率：95%+
内存使用: 优化后减少 30% 内存占用
CPU开销: 脱敏算法优化，减少 40% CPU使用
处理速度: 大批量日志处理速度提升 50%

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

BSD-3-Clause License

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

koatty_logger

✨ 特性

🔒 安全特性

⚡ 性能优化

📦 安装

🚀 快速开始

基础使用（推荐大多数场景）

高级用法（多实例场景）

Fatal 日志级别 (v2.7+)

安全配置

高级用法

🔧 API 文档

Logger 类

构造函数

主要方法

配置选项

🛡️ 安全最佳实践

1. 路径安全

2. 敏感数据保护

3. 注入防护

4. 异步日志最佳实践

5. 批量写入最佳实践

🚀 增强功能

特性概览

使用增强功能

缓冲配置

日志采样

级别过滤

综合示例

环境变量配置

🔍 测试

📊 性能指标

🤝 贡献

📄 许可证