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

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

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

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

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

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

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

## 中文简介

自定义应用度量衡由Amazon Cloud Watch支持(通过嵌入量子格式).

## 安装

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

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

## README

# 计量

自定义应用度量衡由Amazon Cloud Watch支持(通过嵌入量子格式).

**何时使用 :** 您需要跟踪随时间推移的数值测量——请求计数,出错率,耐久性,队列深度,商业KPI. 对仪表板,警报器,以及操作能见度都有好处.

**不使用时 :** 如果需要结构化的日志输出,请使用 `Logging`。如果需要分布式请求跟踪,则使用 `Tracing`。如果需要存储用于查询的时间序列数据,则使用 `Database` 或者说 `DistributedTable`。 。 。 .

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

## API 密码

```typescript
const metrics = new Metrics(scope, id, options?)
```

| 方法 | 回返 | 说明 |
| --- | --- | --- |
| `emit(name, value, options?)` | `void` | 通过EMF记录一个单一的度量数据点. |
| `emitBatch(metrics)` | `void` | 在一个EMF文档中记录多个度量数据点(最大为100个). |
| `flush()` | `void` | 无( EMF 写作即时) 。 提供了接口兼容性 . |
| `child(dimensions)` | `MetricsEmitter` | 创建具有继承命名空间和合并维度的儿童发射器 . |
| `Metrics.fromExisting(namespace)` | `ExternalMetricsRef` | 包存先前存在的 Cloud Watch 命名空间 . |

### 选项

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `namespace` | `string` | 云观察取名空间. 默认为 `scope.fullId`。 。 。 . |
| `defaultDimensions` | `Record<string, string>` | 每一次发射都适用尺寸。 每米维度在上方合并(每米在冲突中获胜). |
| `metrics` | `ExternalMetricsRef` | 将已有的 Cloud Watch 命名空间而不是创建 。 设定时, `namespace` 被忽略. |
| `logger` | `ChildLogger` | 内部操作的可选日志。 省略时,会在错误级别创建默认 Logger . |

### 释放选项

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `unit` | `MetricUnit` | 计量值的单位。 默认为 `'None'`。 。 。 . |
| `dimensions` | `Record<string, string>` | 此数据点的尺寸( 最大共30个, 包括默认值) . |
| `timestamp` | `Date` | 数据点的时间戳 。 默认现在. |
| `resolution` | `MetricResolution` | `'standard'` (60s,默认)或 `'high'` (1s,高成本). |

### 计量单位

```typescript
type MetricUnit =
  | 'Count' | 'Seconds' | 'Milliseconds' | 'Microseconds'
  | 'Bytes' | 'Kilobytes' | 'Megabytes' | 'Gigabytes'
  | 'Percent' | 'Bits/Second' | 'None';
```

### 处理错误

```typescript
import { isBlocksError } from '@aws-blocks/core';
import { MetricsErrors } from '@aws-blocks/bb-metrics';

try {
  metrics.emit('', 1);
} catch (e: unknown) {
  if (isBlocksError(e, MetricsErrors.InvalidMetricName)) {
    // metric name is empty or exceeds 1024 characters
  }
}
```

| 错误 | 条件 |
| --- | --- |
| `MetricsErrors.InvalidMetricName` | 计量名为空或超过1024个字符. |
| `MetricsErrors.InvalidDimensions` | 尺寸超过30个条目,或包含空密钥/值,或密钥/值超过1024个字符. |
| `MetricsErrors.BatchTooLarge` | 批量包含100多公分. |
| `MetricsErrors.InvalidNamespace` | 命名空间为空, 太长, 包含无效字符, 或使用保留 `AWS/` 前缀. |

## 实例

### 基本用途

```typescript
import { Scope, ApiNamespace } from '@aws-blocks/blocks';
import { Metrics } from '@aws-blocks/bb-metrics';

const scope = new Scope('my-app');
const metrics = new Metrics(scope, 'appMetrics', {
  namespace: 'MyApp/Orders',
  defaultDimensions: { service: 'orders' },
});

export const api = new ApiNamespace(scope, 'api', (context) => ({
  async handleRequest() {
    metrics.emit('RequestCount', 1, { unit: 'Count' });
    metrics.emit('Latency', 42, { unit: 'Milliseconds' });
    return { ok: true };
  },
}));
```

### 带有尺寸的释放

```typescript
metrics.emit('RequestCount', 1, {
  unit: 'Count',
  dimensions: { endpoint: '/api/users', method: 'GET' },
});
```

### 批发

```typescript
metrics.emitBatch([
  { name: 'RequestCount', value: 1, unit: 'Count' },
  { name: 'Latency', value: 42, unit: 'Milliseconds' },
  { name: 'ErrorCount', value: 0, unit: 'Count' },
]);
```

### 儿童用品(范围)

```typescript
const requestMetrics = metrics.child({ endpoint: '/api/users', method: 'GET' });
requestMetrics.emit('RequestCount', 1);
requestMetrics.emit('Latency', 35, { unit: 'Milliseconds' });
```

孩子们继承了父母的取名空间和默认维度,将自己在顶上合并. 儿童可以任意筑巢.

### 环绕已存在的命名空间

```typescript
const legacy = new Metrics(scope, 'legacy', {
  metrics: Metrics.fromExisting('MyOrg/SharedMetrics'),
});
legacy.emit('MigrationCount', 1);
```

### 高分辨率度量衡

```typescript
metrics.emit('CPUSpike', 95.2, {
  unit: 'Percent',
  resolution: 'high', // 1-second aggregation
});
```

## CDK 配置

CDK 构造不创建 AWS 资源 。 它只会解决和暴露 `namespace` 财务报告和审定财务报表 `defaultDimensions` 为 CDK-time 消费者只读属性.

EMF使用Cloud Watch日志(Lambda已经对此有权限),因此没有环境变量或 `cloudwatch:PutMetricData` 需要IAM赠款。 在第一个测量数据点到达时默认创建了CloudWatch命名空间.

## 同步 API 理由说明

所有计量方法返回 `void`没有 `Promise<void>`这是故意的:

-   **EMF 写入 stdout** —— 说 `process.stdout.write()` 是 Linux 上一个同步的、非屏蔽的呼叫。 内核缓冲出写作,兰布达的伐木代理人同步捕捉.
-   **无网络 I/ 欧** - 与众不同 `PutMetricData` (这让HTTP呼叫Cloud Watch),"云表日志"上的EMF猪背,Lambda已经流出. 没有什么 `await`。 。 。 .
-   **无** ——回归承诺将增加零效益的微任务时间安排。 量子应该像一个便宜的 `console.log`。 。 。 .
-   **火和遗忘的语义** ——计量是可观察性数据,不是商业批判性写作. 如果一个公尺未放出(例如stdout被关闭),它不应该崩溃请求.

这种设计意味着你可以在任何地方——在热回环,同步回调,或错误处理器——发射出度量衡,而不必担心同源上下文或未处理的承诺拒绝.

## 最佳做法

-   维度基本值保持低(避免用户ID或请求ID作为维度)
-   在整个应用程序中使用一致的公尺名称
-   使用 `defaultDimensions` 共享上下文(服务名称、环境)
-   偏爱 `emitBatch` 在一个请求中记录多个参数时
-   使用单元启用 Cloud Watch 仪表板中的自动转换
-   使用 `child()` 避免相关衡量尺度中重复维度

## 缩放成本( AWS)

-   **摄取量 :** Cloud Watch 通过EMF接受无限度量度——没有 API 调用限制
-   **标准分辨率( 60s):** 完全解析后保留15天,再汇总
-   **高分辨率(1s):** 完全解析后保留3小时,再汇总
-   **费用:** 具有独特的计量名称+尺寸组合的尺度(~0.30美元/度/月)
-   **延迟 :** EMF 在请求中添加了零延迟( studout write is no blocking)

## 地方发展

Metrics被写为EMF JSON来stdout——与AWS格式相同. 在本地dev中,可以在终端输出中看到公分量排放. 没有磁盘的持久性——衡量标准在当地是平面的(与KVStore或分布式表不同,它们坚持 `.bb-data/`) (中文(简体) ).

删去任何要重置的字句——没有当地的国家可以清除.

## 常见问题

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

自定义应用度量衡由Amazon Cloud Watch支持\(通过嵌入量子格式\)\.

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

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

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

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

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

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

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

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

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

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

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