@ geekmidas/ logger (英语)
一个简单而灵活的结构化的日志库,用于Node.js和浏览器,有孩子日志支持和上下文继承功能.
特征
- 标准接口: 具有多个日志级别(调试、信息、警告、错误、致命、跟踪)的常见日志界面
- 结构化日志: 支持结构化的(对象+消息)和简单的(仅信息)记录
- 儿童伐木者: 创建带有继承上下文的儿童日志
- 多个执行: 简单使用的控制台Logger,生产使用的 PinoLogger
- 敏感数据编辑: 内置密码、 令牌、 API 密钥等编辑器
- 类型脚本: 完整类型脚本支持和类型安全记录
安装
pnpm add @geekmidas/logger
快速启动
import { ConsoleLogger } from '@geekmidas/logger';
// Create logger with initial context
const logger = new ConsoleLogger({ app: 'myApp', version: '1.0.0' });
// Structured logging
logger.info({ userId: 123, action: 'login' }, 'User logged in');
// Output: { app: 'myApp', version: '1.0.0', userId: 123, action: 'login', ts: 1234567890 } User logged in
// Simple logging
logger.info('Application started');
// Output: { app: 'myApp', version: '1.0.0', ts: 1234567890 } Application started
// Error logging
logger.error({ error, operation: 'fetchUser' }, 'Failed to fetch user');
皮诺·洛格
对于生产用途,该包提供了一种基于皮诺的对接机,具有高性能和内置的编辑支持.
import { createLogger } from '@geekmidas/logger/pino';
const logger = createLogger({
level: 'info',
pretty: true, // Pretty printing in development
redact: true, // Enable sensitive data redaction
});
logger.info({ userId: 123 }, 'User logged in');
敏感数据编辑
皮诺登录器包括内置编辑器,以自动遮盖密码,令牌等敏感数据以及API密钥.
用默认启用
import { createLogger } from '@geekmidas/logger/pino';
const logger = createLogger({ redact: true });
// Sensitive data is automatically masked
logger.info({ password: 'secret123', user: 'john' }, 'Login attempt');
// Output: { password: '[Redacted]', user: 'john' } Login attempt
logger.info({ headers: { authorization: 'Bearer xyz' } }, 'Request');
// Output: { headers: { authorization: '[Redacted]' } } Request
默认已编辑字段
何时 redact: true,以下字段自动被遮盖:
- 认证数字 :
password, (中文(简体) ),pass, (中文(简体) ),passwd, (中文(简体) ),secret, (中文(简体) ),token, (中文(简体) ),accessToken, (中文(简体) ),refreshToken, (中文(简体) ),apiKey, (中文(简体) ),api_key, (中文(简体) ),authorization, (中文(简体) ),credentials - 页眉数字 :
headers.authorization, (中文(简体) ),headers.cookie, (中文(简体) ),headers["x-api-key"] - 个人数据数字 :
ssn, (中文(简体) ),creditCard, (中文(简体) ),cardNumber, (中文(简体) ),cvv, (中文(简体) ),pin - 秘诀数字 :
connectionString, (中文(简体) ),databaseUrl - 通关卡数字 :
*.password, (中文(简体) ),*.secret, (中文(简体) ),*.token(渔获物嵌入地)
添加自定义路径( 带有默认的路径)
const logger = createLogger({
redact: ['user.ssn', 'payment.cardNumber'],
});
// Both custom paths AND defaults are redacted
logger.info({ password: 'secret', user: { ssn: '123-45-6789' } }, 'Data');
// Output: { password: '[Redacted]', user: { ssn: '[Redacted]' } } Data
覆盖默认
使用 resolution: 'override' 以禁用默认路径, 只使用您的自定义路径 :
const logger = createLogger({
redact: {
paths: ['myCustomSecret'],
resolution: 'override',
},
});
// Only 'myCustomSecret' is redacted, defaults are ignored
logger.info({ password: 'visible', myCustomSecret: 'hidden' }, 'Data');
// Output: { password: 'visible', myCustomSecret: '[Redacted]' } Data
自定义检查并删除
// Custom censor string
const logger = createLogger({
redact: {
paths: ['secret'],
censor: '***HIDDEN***',
},
});
// Remove fields entirely instead of masking
const logger2 = createLogger({
redact: {
paths: ['temporaryData'],
remove: true,
},
});
路径语法
编辑路径支持点标记和通配符 :
redact: [
'password', // Top-level field
'user.password', // Nested field
'users[*].password', // Array wildcard
'*.secret', // Any object's 'secret' field
'headers["x-api-key"]', // Bracket notation for special chars
]
API 参考
锁定接口
interface Logger {
debug: LogFn;
info: LogFn;
warn: LogFn;
error: LogFn;
fatal: LogFn;
trace: LogFn;
child: (obj: object) => Logger;
}
日志级别
- 追踪 - 最详细的资料
- 调试 - 调试的口头信息
- 资讯 - 一般信息信息
- 警告( e) - 可能有害的情况
- 错误 - 仍然允许应用程序继续下去的错误事件
- 致命的 - 可能导致应用程序中止的严重错误
控制台
class ConsoleLogger implements Logger {
constructor(data?: object)
debug: LogFn
info: LogFn
warn: LogFn
error: LogFn
fatal: LogFn
trace: LogFn
child(obj: object): Logger
}
用法实例
基本日志
import { ConsoleLogger } from '@geekmidas/logger';
const logger = new ConsoleLogger({ service: 'api', environment: 'production' });
// Different log levels
logger.trace('Entering function');
logger.debug({ query: 'SELECT * FROM users' }, 'Executing query');
logger.info({ requestId: 'abc123' }, 'Request received');
logger.warn({ memoryUsage: '90%' }, 'High memory usage detected');
logger.error({ error: new Error('Connection failed') }, 'Database error');
logger.fatal({ exitCode: 1 }, 'Critical system failure');
结构化日志
const logger = new ConsoleLogger({ app: 'myApp' });
// Log with context object
logger.info(
{
userId: 123,
action: 'purchase',
productId: 'prod_456',
amount: 29.99
},
'Purchase completed'
);
// Multiple additional arguments
logger.info(
{ traceId: 'trace_123' },
'Request processed in %dms',
150
);
儿童伐木者
儿童记录员从父母那里继承所有上下文,并添加自己的:
const parentLogger = new ConsoleLogger({
app: 'myApp',
environment: 'production'
});
// Create child logger for authentication module
const authLogger = parentLogger.child({ module: 'auth' });
authLogger.info({ userId: 123 }, 'User authenticated');
// Output: { app: 'myApp', environment: 'production', module: 'auth', userId: 123, ts: ... }
// Create child logger for database module
const dbLogger = parentLogger.child({ module: 'database' });
dbLogger.debug({ query: 'SELECT ...' }, 'Query executed');
// Output: { app: 'myApp', environment: 'production', module: 'database', query: 'SELECT ...', ts: ... }
// Child loggers can be nested
const userDbLogger = dbLogger.child({ table: 'users' });
userDbLogger.info({ rowsAffected: 1 }, 'Record inserted');
// Output: { app: 'myApp', environment: 'production', module: 'database', table: 'users', rowsAffected: 1, ts: ... }
请求上下文模式
import type { Logger } from '@geekmidas/logger';
function handleRequest(logger: Logger, requestId: string) {
// Create request-scoped logger
const requestLogger = logger.child({ requestId });
requestLogger.info('Processing request');
try {
processPayment(requestLogger);
requestLogger.info('Request completed');
} catch (error) {
requestLogger.error({ error }, 'Request failed');
}
}
function processPayment(logger: Logger) {
const paymentLogger = logger.child({ operation: 'payment' });
paymentLogger.debug({ amount: 100 }, 'Processing payment');
// All context is preserved: { requestId, operation, amount, ts }
}
与服务一体化
class UserService {
private logger: Logger;
constructor(logger: Logger) {
this.logger = logger.child({ service: 'UserService' });
}
async createUser(data: UserData) {
this.logger.info({ email: data.email }, 'Creating user');
try {
const user = await this.db.insert(data);
this.logger.info({ userId: user.id }, 'User created successfully');
return user;
} catch (error) {
this.logger.error({ error, email: data.email }, 'Failed to create user');
throw error;
}
}
async deleteUser(userId: string) {
const logger = this.logger.child({ userId, operation: 'delete' });
logger.info('Deleting user');
await this.db.delete(userId);
logger.info('User deleted');
}
}
自定义 Logger 执行
您可以执行 Logger 自定义日志后端的接口 :
import type { Logger, LogFn } from '@geekmidas/logger';
class CustomLogger implements Logger {
constructor(private context: object = {}) {}
private createLogFn(level: string): LogFn {
return (obj: any, msg?: string, ...args: any[]) => {
// Your custom logging implementation
const logEntry = {
level,
...this.context,
...obj,
timestamp: new Date().toISOString(),
message: msg
};
// Send to your logging service
yourLoggingService.send(logEntry);
};
}
debug: LogFn = this.createLogFn('debug');
info: LogFn = this.createLogFn('info');
warn: LogFn = this.createLogFn('warn');
error: LogFn = this.createLogFn('error');
fatal: LogFn = this.createLogFn('fatal');
trace: LogFn = this.createLogFn('trace');
child(obj: object): Logger {
return new CustomLogger({ ...this.context, ...obj });
}
}
类型脚本支持
库以 TypeScript 书写,并提供完整类型定义:
import type { Logger, LogFn } from '@geekmidas/logger';
// Use Logger type for dependency injection
function createService(logger: Logger) {
return {
doWork() {
logger.info('Working...');
}
};
}
// LogFn type for custom implementations
const customLog: LogFn = (obj, msg) => {
console.log(obj, msg);
};
最佳做法
-
创建 Base Logger 早期: 在应用程序启动时以静态上下文初始化您的基准日志
const baseLogger = new ConsoleLogger({ app: 'myApp', version: process.env.APP_VERSION, environment: process.env.NODE_ENV }); -
使用儿童搜索器: 创建不同模块/文字的儿童记录器,而不是反复传递上下文
const authLogger = baseLogger.child({ module: 'auth' }); const dbLogger = baseLogger.child({ module: 'db' }); -
结构覆盖字符串: 优先使用上下文对象在字符串连接上进行结构记录
// Good logger.info({ userId, action: 'login', ip }, 'User logged in'); // Avoid logger.info(`User ${userId} logged in from ${ip}`); -
包含上下文: 添加相关上下文, 使日志可以搜索和调试
logger.error({ error: err, userId, requestId, operation: 'fetchUser' }, 'Operation failed'); -
依赖性注射:通过记录器作为依赖性而不是全球进口
class MyService { constructor(private logger: Logger) {} }
许可证
麻省理工学院