@lark-apaas/nestjs-logger 0.1.0-alpha.1 → 0.1.0-alpha.10

package/README.md

@@ -0,0 +1,292 @@
+# NestJS Logger
+
+基于 Pino 的高性能 NestJS 日志库，支持请求追踪和结构化日志。
+
+## 功能特性
+
+- 基于 Pino 的高性能日志记录
+- 自动 HTTP 请求追踪（双层日志：info 链路日志 + verbose 详细日志）
+- 请求和响应体日志记录（可配置）
+- 支持多日志级别
+- 独立的 trace 日志文件
+- 请求上下文传递
+- 日志体长度截断
+
+## 安装
+
+```bash
+npm install @lark-apaas/nestjs-logger
+```
+
+## 基本使用
+
+### 1. 导入模块
+
+```typescript
+import { Module } from '@nestjs/common';
+import { LoggerModule } from '@lark-apaas/nestjs-logger';
+
+@Module({
+  imports: [LoggerModule],
+})
+export class AppModule {}
+```
+
+### 2. 使用 Logger
+
+```typescript
+import { Injectable, Logger } from '@nestjs/common';
+
+@Injectable()
+export class MyService {
+  private readonly logger = new Logger(MyService.name);
+
+  doSomething() {
+    this.logger.log('This is an info log');
+    this.logger.debug('This is a debug log');
+    this.logger.warn('This is a warning');
+    this.logger.error('This is an error', error.stack);
+  }
+}
+```
+
+## 环境变量配置
+
+### 基础配置
+
+```bash
+# 日志级别: trace, debug, info, warn, error, fatal, silent
+# 注意：HTTP 请求追踪日志使用 verbose 级别（对应 Pino 的 trace）
+# 生产环境默认为 info，不会打印 verbose 级别的日志
+LOGGER_LEVEL=info
+
+# 日志目录
+LOG_DIR=logs
+
+# Node 环境（默认：开发环境使用 debug，生产环境使用 info）
+NODE_ENV=production
+```
+
+### 请求/响应体日志配置
+
+```bash
+# 启用请求体日志（默认：false）
+LOG_REQUEST_BODY=true
+
+# 启用响应体日志（默认：false）
+LOG_RESPONSE_BODY=true
+
+# 注意：即使启用了请求/响应体日志，也需要将日志级别设置为 verbose 才能实际输出
+# 因为 HTTP 请求追踪日志使用的是 verbose 级别
+LOGGER_LEVEL=verbose
+
+# 日志体最大长度，超过会截断（默认：不限制）
+# 不设置此环境变量时，不会进行截断
+LOG_MAX_BODY_LENGTH=10000
+```
+
+## 请求/响应体日志
+
+### 日志级别说明
+
+HTTP 请求追踪日志使用 **`verbose` 级别**（对应 Pino 的 `trace` 级别），这意味着：
+
+- **生产环境默认不打印**：生产环境默认日志级别为 `info`，不会输出 verbose 级别的日志
+- **需要显式启用**：要查看 HTTP 请求追踪日志，需要将 `LOGGER_LEVEL` 设置为 `verbose`
+- **细粒度控制**：可以通过日志级别控制是否打印请求追踪，而无需修改 `LOG_REQUEST_BODY` 和 `LOG_RESPONSE_BODY` 配置
+
+### 启用方式
+
+通过环境变量启用：
+
+```bash
+# 方式一：仅启用 HTTP 请求追踪（不包含 body）
+LOGGER_LEVEL=verbose
+
+# 方式二：启用 HTTP 请求追踪 + 请求/响应体
+LOGGER_LEVEL=verbose
+LOG_REQUEST_BODY=true
+LOG_RESPONSE_BODY=true
+```
+
+### 重要说明
+
+1. **双层日志机制**：
+   - **info 级别**：始终记录基础链路日志（不含 body），用于生产环境请求追踪
+   - **verbose 级别**：记录详细追踪日志（包含 body），用于开发调试
+
+2. **默认不限制长度**：如果不设置 `LOG_MAX_BODY_LENGTH` 环境变量，日志体不会被截断。建议在生产环境设置合理的限制值。
+
+3. **响应数据处理**：日志库会尝试序列化所有响应数据，对于无法序列化的数据（如 Buffer、Stream）会返回类型信息。
+
+### 日志输出示例
+
+#### Info 级别（链路日志）
+
+```json
+{
+  "level": "INFO",
+  "time": 1234567890,
+  "msg": "HTTP request started",
+  "method": "GET",
+  "path": "/api/users",
+  "trace_id": "req-123-456",
+  "user_id": "user-001",
+  "tenant_id": 24020896,
+  "app_id": "",
+  "context": "HTTPTraceInterceptor"
+}
+```
+
+```json
+{
+  "level": "INFO",
+  "time": 1234567890,
+  "msg": "HTTP request completed",
+  "method": "GET",
+  "path": "/api/users",
+  "trace_id": "req-123-456",
+  "status_code": 200,
+  "duration_ms": 125,
+  "context": "HTTPTraceInterceptor"
+}
+```
+
+#### Verbose 级别（详细追踪日志）
+
+```json
+{
+  "level": "TRACE",
+  "time": 1234567890,
+  "msg": "HTTP request started",
+  "method": "POST",
+  "path": "/api/users",
+  "trace_id": "req-123-456",
+  "request_body": {
+    "username": "john_doe",
+    "email": "john@example.com",
+    "password": "secret123"
+  },
+  "query_params": {
+    "filter": "active"
+  },
+  "context": "HTTPTraceInterceptor"
+}
+```
+
+```json
+{
+  "level": "TRACE",
+  "time": 1234567890,
+  "msg": "HTTP request completed",
+  "method": "POST",
+  "path": "/api/users",
+  "trace_id": "req-123-456",
+  "status_code": 201,
+  "duration_ms": 125,
+  "response_body": {
+    "id": "user-123",
+    "username": "john_doe",
+    "email": "john@example.com"
+  },
+  "context": "HTTPTraceInterceptor"
+}
+```
+
+## 数据截断
+
+默认情况下，不会对日志体进行截断。当设置 `LOG_MAX_BODY_LENGTH` 环境变量后，如果请求/响应体超过指定长度，会自动截断：
+
+```json
+{
+  "response_body": {
+    "_truncated": true,
+    "_originalLength": 50000,
+    "_data": "{ 前 10000 个字符... }..."
+  }
+}
+```
+
+**建议**：在生产环境设置合理的限制值（如 10000），避免单条日志过大。
+
+## 日志级别映射
+
+NestJS LoggerService 级别到 Pino 级别的映射：
+
+- `fatal` → `fatal`
+- `error` → `error`
+- `warn` → `warn`
+- `log` → `info`
+- `debug` → `debug`
+- `verbose` → `trace`
+
+## 日志文件
+
+日志会写入以下文件（默认在 `logs/` 目录）：
+
+- `app.log` - 应用日志
+- `trace.log` - HTTP 请求追踪日志
+
+## 注意事项
+
+### 安全性
+
+1. **生产环境默认不打印 HTTP 追踪日志**：由于使用 verbose 级别，生产环境（info 级别）默认不会输出详细日志
+2. **双层日志设计**：info 级别始终记录链路日志，verbose 级别记录详细信息，按需启用
+3. **按需启用**：需要查看详细追踪时，将 LOGGER_LEVEL 设置为 verbose
+4. **敏感数据处理**：日志库不提供脱敏功能，请在业务层或通过中间件处理敏感数据
+
+### 性能
+
+1. verbose 级别会输出所有 HTTP 请求详细日志，可能影响性能
+2. 开启请求/响应体日志会增加日志体积和 I/O 开销
+3. 大对象的序列化会影响性能
+4. 建议在开发/测试环境使用，生产环境按需临时启用
+
+### 存储
+
+1. 日志直接写入文件，不支持自动轮转，建议通过外部工具（如 logrotate）管理日志文件
+2. verbose 级别 + 请求/响应体日志会显著增加日志量
+3. 建议设置 `LOG_MAX_BODY_LENGTH` 限制单条日志大小（默认不限制）
+
+## 最佳实践
+
+### 开发环境
+
+```bash
+NODE_ENV=development
+# 使用 verbose 级别查看 HTTP 请求追踪
+LOGGER_LEVEL=verbose
+LOG_REQUEST_BODY=true
+LOG_RESPONSE_BODY=true
+# 开发环境可以不限制长度，或设置较大值
+# LOG_MAX_BODY_LENGTH=50000
+```
+
+### 生产环境
+
+```bash
+NODE_ENV=production
+# 生产环境使用 info 级别，不会打印 HTTP 请求追踪日志
+LOGGER_LEVEL=info
+# 这两个配置可以保留，只有当 LOGGER_LEVEL=verbose 时才会生效
+LOG_REQUEST_BODY=false
+LOG_RESPONSE_BODY=false
+```
+
+### 故障排查
+
+临时启用详细日志：
+
+```bash
+NODE_ENV=production
+# 临时开启 verbose 级别查看 HTTP 请求追踪
+LOGGER_LEVEL=verbose
+LOG_REQUEST_BODY=true
+LOG_RESPONSE_BODY=true
+LOG_MAX_BODY_LENGTH=10000  # 建议设置限制，避免日志过大
+```
+
+## License
+
+MIT