# @aws-blocks/bb-logger 中文文档

规范地址：https://npmcn.com/package/%40aws-blocks/bb-logger/

版本：0\.3\.0
npm 元数据更新时间：2026-11-02T10:25:05.989Z
中文译文更新时间：2026-11-07T12:56:25.887Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aws-blocks/bb-logger
原文对照：https://npmcn.com/package/%40aws-blocks/bb-logger/?lang=original
项目主页：https://github.com/aws-devtools-labs/aws-blocks/tree/main/packages/bb-logger#readme
源码仓库：https://github.com/aws-devtools-labs/aws-blocks

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

- 包体积（解压后）：121 kB，48 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：constructs ^10\.6\.0，aws-cdk-lib ^2\.257\.0
- 首次发布：2026-06-15T23:39:42.684Z
- 最新版本发布：2026-11-02T10:25:05.641Z
- 近 30 天下载量：65644（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

结构化记录,采用一致的JSON格式、日志级别和背景元数据.

## 安装

```sh
npm install @aws-blocks/bb-logger
```

也可以使用：`pnpm add @aws-blocks/bb-logger`、`yarn add @aws-blocks/bb-logger`、`bun add @aws-blocks/bb-logger`

## README

# @ aws- blocks/ bb- logger (缩写)

结构化记录,采用一致的JSON格式、日志级别和背景元数据.

> 设计与模拟等价细节 : [设计](https://npmcn.com/package/%40aws-blocks/bb-logger/DESIGN.md)

## 何时使用

-   您需要结构化且可查询的应用程序日志
-   您想要在您的后端显示一致的日志格式
-   您需要请求扫描的带有相关标识的日志
-   您需要不修改代码的日志级别过滤

## 不使用时

-   用于一段时间内的数值测量 − 使用 `Metrics`
-   用于分发的追查请求 `Tracing`

## 快速启动

```typescript
import { Scope } from '@aws-blocks/core';
import { Logger } from '@aws-blocks/bb-logger';

const scope = new Scope('my-app');
const log = new Logger(scope, 'app');

log.info('Server started', { port: 3000 });
log.warn('Slow query', { durationMs: 1500 });
log.error('Request failed', { err: new Error('timeout') });
```

## API 密码

### 构造器

```typescript
new Logger(scope: ScopeParent, id: string, options?: LoggingOptions)
```

**选项 :**

-   `level` 最低对数水平`'debug' | 'info' | 'warn' | 'error'`) (中文(简体) ). 默认 : `'info'`。 。 。 .
-   `defaultContext` ——每个日志条目包含字段.

日志保存不是一个 Logger 选项——它是一个计算级别设置(参见 [保留](https://npmcn.com/package/%40aws-blocks/bb-logger/#readme-retention-production) 页:1.

### 方法

```typescript
log.debug(message: string, context?: Record<string, unknown>): void
log.info(message: string, context?: Record<string, unknown>): void
log.warn(message: string, context?: Record<string, unknown>): void
log.error(message: string, context?: Record<string, unknown>): void
log.child(context: Record<string, unknown>): ChildLogger
```

所有日志方法都是 **同步** (无需等待).

### 日志条目格式

每个日志条目都是写为 stdout(或错误的 stderr)的 JSON 对象 :

```json
{
  "level": "info",
  "message": "User logged in",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "logger": "app",
  "userId": "user-123"
}
```

### 儿童伐木者

创建继承上下文的请求范围日志 :

```typescript
const requestLog = log.child({ requestId: 'req-abc', userId: 'u-123' });
requestLog.info('Processing request');
// Output includes requestId and userId automatically
```

儿童可以筑巢:

```typescript
const dbLog = requestLog.child({ component: 'database' });
dbLog.warn('Slow query', { table: 'users', durationMs: 500 });
```

## 日志级别

1.  构造器 `level` 选项
2.  默认 : `'info'`

设置水平每 `Logger` 通过 `level` 选项。 没有 `LOG_LEVEL` 环境 var-log level是运行时的构造-时间选择.

## 对象处理出错

上下文中通过的错误实例会自动提取 :

```typescript
try {
  await doSomething();
} catch (err) {
  log.error('Operation failed', { err });
  // err is serialized as { name, message, stack }
}
```

## 序列安全

记录员处理边缘案件时优雅:

-   **通知参考** 改为: `"[Circular]"`
-   **大内值** → 转换为字符串
-   **函数/符号** 改为: `"[unserializable]"`
-   **上下文错误** − 提取到 `{ name, message, stack }`

## 保留(生产)

**记录总是在进行,保留是一个计算级设置,而不是一个 Logger 选项.** 每一次计算都会捕捉到它处理器的积分到它自己的"云表"日志 组,该组带有全堆积默认保留(`defaults.logRetention` —— 说 在沙盒里呆一周,生产一年).

要更改保留, 设置 `logRetention` 在堆放层上 `defaults` (适用 到每个计算器的处理日志组 :

```typescript
import { BlocksPresets } from '@aws-blocks/core/cdk';
import { RetentionDays } from 'aws-cdk-lib/aws-logs';

// In your aws-blocks backend, override the preset's logRetention:
defaults: { ...BlocksPresets.production, logRetention: RetentionDays.ONE_MONTH };
```

A 类 `Logger` 不再重新配置保留——计算拥有单曲, 框架拥有的处理器日志组。 按计算留存额(a) `logRetention` 道具 在计算时)与公共计算配置表面相接而来 这么说吧, `defaults.logRetention` 是保留键.

## 地方发展

当地 dev(`npm run dev`),"Logger BB:"(英语:Logger BB:

-   将结构化的 JSON 写入 stdout/ stderr (与生产相同)
-   不将日志粘入磁盘
-   不在其中创建任何文件 `.bb-data/`
-   保留没有局部效果( 它是一个只用云, 计算级别设置)
-   日志级别来自 `Logger`是因为 `level` 选项(默认) `'info'`(中文(简体) )

## 错误

```typescript
import { LoggingErrors } from '@aws-blocks/bb-logger';

LoggingErrors.SerializationFailed // 'SerializationFailedException'
```

此错误在上下文时用作已退化日志条目中的标记 序列化失败( 不扔给消费者) .

## 常见问题

### @aws-blocks/bb-logger 是什么？

结构化记录,采用一致的JSON格式、日志级别和背景元数据\.

### 如何安装 @aws-blocks/bb-logger？

在项目目录运行 npm install @aws-blocks/bb-logger，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：constructs（^10\.6\.0）、aws-cdk-lib（^2\.257\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws-blocks/bb-logger 支持 TypeScript 吗？

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

### @aws-blocks/bb-logger 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @aws-blocks/bb-logger 可以商用吗？

@aws-blocks/bb-logger 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aws-blocks/bb-logger 的下载量有多少？

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

### @aws-blocks/bb-logger 还在维护吗？

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