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

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

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

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

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

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

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

## 中文简介

由AWS X-Ray支持的分布式追踪.

## 安装

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

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

## README

# 追踪器

由AWS X-Ray支持的分布式追踪.

> **全舰队+费用:** \* 追踪是显示存在的——构建 **任意** `Tracer` 在应用程序中启用 X-Ray 活动模式 **每个** 计算(X-Ray为每张账单) 追踪记录/检索. `enabled: false` 编号 `Tracer` 只删除 _那个_ 追踪器的选入; 如果有其它 `Tracer` 已经存在, X -Ray 仍然打开整个舰队.

**何时使用 :** 您需要追踪服务之间的请求流量,调试时空问题,或者可视化服务依赖性. 善于识别瓶颈,理解呼叫链, 并关联到整个建筑街区的失败.

**不使用时 :** 如果需要结构化的日志输出,请使用 `Logging`。如果随着时间的推移需要数字测量,请使用 `Metrics`。 。 。 .

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

## 安装

```bash
npm install @aws-blocks/bb-tracer
```

## 快速使用

```typescript
import { Tracer } from '@aws-blocks/bb-tracer';

const tracer = new Tracer(scope, 'my-tracer');

// Wrap an operation in a traced segment
const user = await tracer.startSegment('fetchUser', async (segment) => {
  segment.addAnnotation('userId', 'user-123');
  const result = await db.get('user-123');
  segment.setHttpStatus(200);
  return result;
});

// Add root-level annotations (attached to the Lambda facade segment)
tracer.addAnnotation('endpoint', '/api/users');

// Get the current trace ID for log correlation
const traceId = tracer.getTraceId();
```

## API 密码

```typescript
const tracer = new Tracer(scope, id, options?)
```

| 方法 | 回返 | 说明 |
| --- | --- | --- |
| `startSegment(name, fn)` | `Promise<T>` | 在所追踪的子项中设置一个同步函数 。 当 `fn` 完成或抛出. |
| `addAnnotation(key, value)` | `void` | 在根部分添加可搜索注释 . |
| `addMetadata(key, value)` | `void` | 将不可搜索的元数据添加到根段 . |
| `getTraceId()` | `string | null` | 获取当前日志关联的跟踪ID 。 回返 `null` 当残疾. |

### 方法

这个 `segment` 对象传递到 `startSegment`'召回:

| 方法 | 说明 |
| --- | --- |
| `addAnnotation(key, value)` | 添加可搜索注释(字符串、数字或布尔). |
| `addMetadata(key, value)` | 添加不可搜索的元数据( 任何 JSON 序列值) . |
| `addError(error)` | 记录一个错误而不重投 . |
| `setHttpStatus(statusCode)` | 记录 HTTP 响应状态代码 . |

### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `enabled` | `boolean` | `true` | 启用或禁用追踪 。 何时 `false`, (中文(简体) ), `startSegment` 仍然执行被包裹的函数. |
| `samplingRate` | `number` | `1.0` | 0至1之间的采样率. 只影响局部的模拟行为. |
| `logger` | `ChildLogger` | —— 说 | 内部操作的可选日志。 省略时,会在错误级别创建默认 Logger . |

## 最佳做法

-   使用 `startSegment` 以包装离散的工作单位( DB 调用、 HTTP 请求、 业务逻辑)
-   保持片段名称简短和描述性(例如:, `'fetchUser'`, (中文(简体) ), `'processPayment'`(中文(简体) )
-   在 X-Ray 控制台对您想要过滤/搜索的值使用注释
-   使用元数据来获取您不需要搜索的大型或复杂的调试数据
-   保留注释基本值低(避免用户特定值作为注释密钥)
-   使用 `AsyncJob` 为长期工作,而不是追踪巨大的跨度

## 地方发展

模拟数据持续到磁盘 `.bb-data/{fullId}/traces.json` 跨 Dev 服务器重启 。 被嵌入的片段被存储为树(子阵列). 擦拭为 `rm -rf .bb-data`。 。 。 .

模拟器以完整的时间,说明,元数据以及出错数据记录所有本地的痕迹——匹配X-Ray在制作中捕获的形状.

## 取样

-   **当地( mock) :** 受控制者控制 `samplingRate` 选项。 价值为 `0.1` 意味着当地大约10%的痕迹被记录下来. 默认是 `1.0` (记录一切).
-   **生产(AWS):** 取样由AWS控制台所配置的X-Ray取样规则或通过CDK控制. 这个 `samplingRate` x-Ray的本土采样基础设施优先.

## 定价

-   **自由等级 :** 每月记录100 000个痕迹,每月扫描/取回100万个痕迹
-   **超过自由级 :** 记录每百万分之5.00分,每百万分之50分,检索或扫描
-   **Lambda 守护进程 :** 没有附加电荷 — X- Ray 守护进程已建入 Lambda 运行时间
-   **成本驱动器:** 追溯引用数×采样率
-   **成本优化:** 配置 X-Ray 采样规则,以保持记录-跟踪量(和成本)在高通量函数( `samplingRate` 选项只影响本地模拟,而不是生产)
-   **残废( E)`enabled: false`:** 零X射线成本——没有记录或发送痕迹

## 另见

-   [类型](https://npmcn.com/package/%40aws-blocks/bb-tracer/src/types.ts) - 共同类型定义(`Segment`, (中文(简体) ), `TracerOptions`, (中文(简体) ), `AnnotationValue`(中文(简体) )

## 常见问题

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

由AWS X-Ray支持的分布式追踪\.

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

在项目目录运行 npm install @aws-blocks/bb-tracer，或使用 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-tracer 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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