# @bernierllc/logger 中文文档

规范地址：https://npmcn.com/package/%40bernierllc/logger/

版本：2\.0\.0
npm 元数据更新时间：2026-11-04T21:06:10.408Z
中文译文更新时间：2026-11-07T23:10:29.643Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bernierllc/logger
原文对照：https://npmcn.com/package/%40bernierllc/logger/?lang=original
项目主页：https://github.com/bernier-llc/tools#readme
源码仓库：https://github.com/bernier-llc/tools

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：22.4 kB，5 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：4 个
- 首次发布：2025-08-28T22:10:33.630Z
- 最新版本发布：2026-11-04T21:06:10.240Z
- 近 30 天下载量：3745（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 13 个）

## 中文简介

结构化伐木,具有多种运输方式、日志水平以及伯尼环礁生态系统的相关跟踪

## 安装

```sh
npm install @bernierllc/logger
```

也可以使用：`pnpm add @bernierllc/logger`、`yarn add @bernierllc/logger`、`bun add @bernierllc/logger`

## README

# @ bernierllc/ 拖放器

生产准备结构化伐木,具有多路运输,日志水平,关联跟踪,伯尼环礁生态系统性能监测.

## 特征

-   **结构化日志**:基于 JSON 的结构化日志输出与元数据
-   **多重运输**: 控制台、文件、HTTP、数据库和自定义运输
-   **日志级别**:可配置的日志水平,并带有过滤(ERROR、WARN、INFO、HTTP、VERBOSE、DEBUG、SILLY)
-   **跟踪**: 请求/跟踪 ID 互联互通
-   **业绩跟踪**: 时间跟踪、定时和剖面分析
-   **数据保密**: 自动 PII 保护和敏感数据掩码
-   **内容管理**: 丰富的上下文和元数据支持
-   **儿童伐木者**: 背景记录继承
-   **Graceful 错误处理**: 运输故障恢复和错误回调

## 安装

```bash
npm install @bernierllc/logger
```

## 快速启动

```typescript
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'));
```

## 用法实例

### 基本日志

```typescript
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: 'user@example.com' });
logger.warn('High memory usage', { memoryUsage: '85%' });
logger.error('Payment failed', new Error('Invalid card'));
```

### 业绩跟踪

```typescript
// 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
```

### 跟踪

```typescript
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
});
```

### 儿童伐木者

```typescript
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
```

### 数据保密

```typescript
const logger = new Logger({
  sanitize: true,
  sanitizeFields: ['password', 'token', 'creditCard', 'ssn'],
  transports: [new ConsoleTransport()]
});

logger.info('User data', {
  username: 'john@example.com',
  password: 'secret123',    // Will be [REDACTED]
  age: 30                   // Will be preserved
});
```

### 自定义运输

```typescript
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()
  ]
});
```

### 多重运输

```typescript
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 参考

### 锁定器

#### 构造器

```typescript
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>` - 关闭伐木机和运输工具

### 日志级别

```typescript
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 格式

产出平整结构日志并有前缀字段.

## 运行时配置

日志员通过配置文件支持运行时间配置,允许您自定义日志行为而不修改代码.

### 快速设置

1.  **初始化配置 :**
    
    ```bash
    npm run config:init
    ```
    
2.  **编辑生成的 `logger.config.js`数字 :**
    
    ```javascript
    module.exports = {
      level: 'info',
      context: {
        service: 'my-service',
        version: '1.0.0'
      },
      console: {
        enabled: true,
        level: 'debug'
      }
    };
    ```
    
3.  **在代码中使用 :**
    
    ```typescript
    import { createLoggerFromConfig } from '@bernierllc/logger';
    
    const logger = await createLoggerFromConfig();
    logger.info('Application started');
    ```
    

### 配置发现

记录器在此顺序下自动发现配置文件 :

1.  `logger.config.js` (JavaScript - 建议)
2.  `logger.config.cjs` (共同JS) (中文(简体) )
3.  `logger.config.mjs` (ES模块)
4.  `logger.config.json` (杰森语)
5.  `package.json` → `"logger"` 键

### CLI 命令

```bash
# Initialize configuration
npm run config:init

# Validate configuration
npm run config:validate

# Print resolved configuration
npm run config:print
```

### 环境变量

所有配置选项都可以被覆盖 `LOGGER_*` 环境变量:

```bash
LOGGER_LEVEL=debug
LOGGER_SERVICE=my-service
LOGGER_CONSOLE_LEVEL=info
LOGGER_FILE_ENABLED=true
LOGGER_FILE_FILENAME=logs/app.log
```

### 完整文档

详细的配置选项、实例和迁移指南见: [Logger 运行时配置文档](https://npmcn.com/package/docs/runtime-config/logger-runtime-config.md)

## 配置

### 锁定选项

```typescript
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
}
```

### 日志语句

```typescript
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
}
```

## 处理错误

日志包括全面处理错误:

```typescript
const logger = new Logger({
  transports: [transport1, transport2],
  onError: (error, transportName) => {
    console.error(`Transport ${transportName} failed:`, error);
    // Handle transport failures (e.g., fallback logging)
  }
});
```

运输故障是孤立的,不影响其他运输或应用执行.

## 业绩

该伐木机被优化用于生产:

-   最小伐木量(每个伐木条目小于1ms)
-   同步传输写入
-   限制有效消息和元数据大小
-   网络运输的智能分批
-   记忆意识关联跟踪

## 最佳做法

1.  **使用适当的日志级别** - 实际出错准备金
2.  **包含上下文** - 在日志条目中添加相关的元数据
3.  **使用关联ID** - 跟踪各种服务的要求
4.  **敏感数据的保密** - 防止PII泄漏
5.  **适当配置运输工具** - 不同产出的不同水平
6.  **使用儿童记录器** - 创建针对上下文的日志
7.  **处理运输故障** - 执行错误回调
8.  **监测业绩** - 使用内置计时功能

## 一体化状况

### 锁定集成

-   **状态**: N/A - 这是核心日志包
-   **使用量**: 其他 BernerLLC 包与这个日志集成,用于整个生态系统的一致记录

### Docs- 成套集成软件

-   **状态**: 准备 - 全类型文件导出支持
-   **格式**: 包含综合API文档的TypeDoc
-   **特征**: 自动文档生成、代码示例和类型定义

### NeverHub 整合

-   **状态**: 综合 - 全面服务发现和事件总线支持
-   **执行情况**数字 :
    -   运行时自动检测 NeverHub 可用性
    -   无法使用 NeverHub 时的分级
    -   在NeverHub存在时增强运输能力
    -   有伐木能力的服务登记
    -   事件驱动日志汇总和转发
-   **能力**数字 :
    -   NeverHub 配置服务的动态配置
    -   利用分布式追踪增强可观察性
    -   通过日志自动报告服务健康情况
    -   跨服务日志关联

## 发展

```bash
# 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 (英语)](https://npmcn.com/package/%40bernierllc/retry-policy) - 用于运输重试逻辑
-   [@bernierllc/csv-parser (英语)](https://npmcn.com/package/%40bernierllc/csv-parser) - 可用此日志调试
-   [@bernierllc/电子邮件发送器](https://npmcn.com/package/%40bernierllc/email-sender) - 可能使用这个记录器进行操作跟踪

## 常见问题

### @bernierllc/logger 是什么？

结构化伐木,具有多种运输方式、日志水平以及伯尼环礁生态系统的相关跟踪

### 如何安装 @bernierllc/logger？

在项目目录运行 npm install @bernierllc/logger，或使用 pnpm add / yarn add / bun add。

### @bernierllc/logger 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bernierllc/logger 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @bernierllc/logger 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @bernierllc/logger 可以商用吗？

@bernierllc/logger 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bernierllc/logger 的下载量有多少？

根据 npm 官方下载统计，@bernierllc/logger 在 2026/10/08 – 2026/11/06 这 30 天内被下载 3,745 次，日均约 125 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bernierllc/logger 还在维护吗？

最新版本 2\.0\.0 发布于 2026/11/05（3 天前）；至今共发布 14 个版本，其中过去 12 个月发布了 13 个；首次发布于 2025/08/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。