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

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

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

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

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

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

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

## 中文简介

自动生成 Cloud Watch Dashboard 用于应用可观察性.

## 安装

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

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

## README

# @aws- blocks/ bb- dashboard (英语)

自动生成 Cloud Watch Dashboard 用于应用可观察性.

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

## 何时使用

-   您已经应用了您的应用程序, 想要一个 URL 来查看应用程序的健康
-   您想要预配置部件而无需手动创建 Cloud Watch 仪表板
-   你需要一个团队仪表板 用于部署验证和操作意识

## 不使用时

-   您需要自定义的可视化或交互式数据探索 使用 Cloud Watch 控制台

## 安装

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

## 快速启动

### 最小值

```typescript
import { Dashboard } from '@aws-blocks/bb-dashboard';

const dashboard = new Dashboard(scope, 'dashboard');
// After deploy: a CloudWatch Dashboard with a health + logs section for every
// compute in the app.
```

### 带有度量衡+追踪器(建议)

仪表板是安排好的 **通过计算** ——应用程序中的每个计算都是一组. 每组显示 **卫生** 节和a **日志** 节( 日志总是 被俘虏). A 类 **跟踪** 当应用程序包含一个 `Tracer` (追踪) 显示显示:任何追踪器每次计算都会打开X-Ray。 没错 **没有** 将 Logger / Tracer 实例传递到仪表板 . **计量** 应用范围(a) 名字空间不是与计算相连的 所以它们被明确通过 一节 每个命名空间.

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

new Tracer(scope, 'tracing');    // → traces section on every compute
const metrics = new Metrics(scope, 'metrics', { namespace: 'MyApp' });

const dashboard = new Dashboard(scope, 'dashboard', {
  title: 'MyApp — Production',
  // Display toggles (default true) applied to every compute section.
  logs: true,
  traces: true,
  // app-wide; pair each Metrics BB with its own metric names (per-namespace).
  // Also accepts an array of sources, one section per namespace.
  metrics: {
    metrics,
    metricConfigs: [
      { name: 'OrdersPlaced' },
      { name: 'Latency', stat: 'p99', period: 300, title: 'P99 Latency' },
      { name: 'CustomMetric', dimensions: { Service: 'API', Stage: 'prod' } },
    ],
  },
});
```

仪表板如何解决每个部分:

-   **卫生** ——计算部健康科,始终显示.
-   **日志** ——每个计算都显示(日志总是被捕获);日志组是计算员自己的处理器日志组. 使用 `logs: false`。 。 。 .
-   **追踪** ——在启用跟踪时显示计算(应用程序包含一个 `Tracer`) (中文(简体) ). 使用 `traces: false`。 。 。 .
-   **计量** - 应用范围,从 `metrics` 选项:使用每个 BB 解析 `namespace` (违约范围) `fullId`和 `defaultDimensions` (包含在部件查询中,以便针对正确的维度流).
-   **计算覆盖率** 总是 **每个** 在应用程序中计算(今天一个). 还没有显示计算选择器 .

## API 参考

### `new Dashboard(scope, id, options?)`

创建带有自动生成部件的 Cloud Watch Dashboard .

**参数:**

| 名称 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `scope` | `ScopeParent` | 对 | 父范围( 范围实例或 BlocksStack) |
| `id` | `string` | 对 | 唯一标识符 |
| `options` | `DashboardOptions` | 没有 | 配置 |

**属性 :**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `url` | `string | null` | 云表 Dashboard 控制台 URL (CfnOutput). `string` cDK 构造; `null` 在默认/模拟类型中,直到部署 |
| `dashboardName` | `string` | 解决的仪表板名称 |

### `DashboardOptions`

#### 显示切换

日志和痕迹是一节 **显示切换**,而不是组成投入—— 仪表板直接读取每个计算器的状态. 日志总是被捕获(因此) `logs` 仅隐藏该部分); 只在应用程序有一个 `Tracer` (这样) `traces` 仅隐藏另列部分.

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `logs` | `boolean` | `true` | 显示每次计算的日志区域 |
| `traces` | `boolean` | `true` | 显示每次计算时的跟踪部分( 仅在应用程序有时出现) `Tracer`(中文(简体) ) |

仪表盘总是覆盖 **每个** 在应用程序中计算。 没有计算 选择者——一个与多计算客户表面一起到达(它将 否则在客户构建计算之前会泄露内部类型.

#### 计量组成

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `metrics` | `MetricsSource | MetricsSource[]` | 量子源——每对有自有量子 BB `metricConfigs`; 每个命名空间一个全应用区域 |

#### 配置

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `title` | `string` | `id` | 显示板标题 |
| `dashboardName` | `string` | `scope.fullId` | Cloud Watch Dashboard 名称(最大为 255个字符,自动刷卡) |
| `defaultTimeRange` | `string` | `'-PT3H'` | 默认时间范围(ISO 8601期限) |
| `routePath` | `string | false` | `'/aws-blocks/dashboard'` | 重定向的路径 。 设定为 `false` 无法禁用 |

### `MetricConfig`

一个预先注册的 Cloud Watch 度量衡的配置 .

| 外地 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `name` | `string` | (必须) | 云表参数名称 |
| `stat` | `'Sum' | 'Average' | 'Maximum' | 'Minimum' | 'p99' | 'p95' | 'p50'` | `'Sum'` | 汇总统计 |
| `period` | `number` | `60` | 集合期( 必须是% 1) 秒 |
| `title` | `string` | 参数名称 | 部件标题覆盖 |
| `dimensions` | `Record<string, string>` | 未定义 | 计量维度至窄范围(例如:, `{ Service: 'API', Stage: 'prod' }`(中文(简体) ) |

## 错误常数

```typescript
import { DashboardErrors } from '@aws-blocks/bb-dashboard';

DashboardErrors.InvalidMetricConfig // 'InvalidMetricConfigException'
```

-   `InvalidMetricConfig`: 当一个参数配置无效时被丢入(例如空名或无效期).

> 说明: `InvalidMetricConfig` 是在 CDK 合成时在构建部件时被抛出,而不是由模拟/运行时间 `Dashboard` 建筑师.

## 自动生成部件

总是包括下列部件:

分组每计算,然后是全应用的度量标准:

| 部件 | 来源 | 条件 |
| --- | --- | --- |
| 兰布达会议 | AWS/兰布达 | 每一次计算,总是 |
| Lambda 错误 | AWS/兰布达 | 每一次计算,总是 |
| Lambda 持续时间(Avg + p99) | AWS/兰布达 | 每一次计算,总是 |
| 同时执行 | AWS/兰布达 | 每一次计算,总是 |
| X-Ray 跟踪表 | X射线 | 按计算,当应用程序有 `Tracer` (除非 `traces: false`(中文(简体) ) |
| 最近的错误( 逻辑透视) | 日志组 | 总是计算(除非 `logs: false`(中文(简体) ) |
| 日志卷 | AWS/日志 | 总是计算(除非 `logs: false`(中文(简体) ) |
| 个人计量图(每公吨) | 用户名空间 | 全应用,每 `metrics` 来源+ `metricConfigs` |

(健康部件为Lambda-形状,用于默认计算;其他计算类型报告自己的健康指标。 )

## Dashboard 重定向路线

Dashboard BB 登记 a `GET` 路径( 默认 ): `/aws-blocks/dashboard`302个方向 转到云表 Dashboard 控制台 URL。 这提供了一种方便的,可以发现的 开发者进入点 。 设定 `routePath: false` 以禁用.

-   **在 AWS 中 :** 重定向到全 Cloud Watch 控制台 URL(需要 AWS 登录) .
-   **在本地 dev 中:** 返回503,并首先部署一个消息.

```typescript
// Custom route path
const dashboard = new Dashboard(scope, 'dashboard', {
  routePath: '/ops/dashboard',
});
// GET /ops/dashboard → 302 → https://<region>.console.aws.amazon.com/cloudwatch/...
```

## 日志组

每个计算器的日志段查询会计算自己的处理器日志组(即 计算条款)。 日志总是被捕获,所以 每个计算都会出现日志部件,除非设置 `logs: false`。 。 。 .

## 地方发展

在本地 dev 模式下, 模拟记录了方向路由, 但返回 503 (因为当地没有云表板):

```
[Dashboard] Dashboard BB: no-op in local mode (CloudWatch Dashboard is a cloud-only resource).
Will create CloudWatch Dashboard 'My App' on deploy. Run 'npx cdk deploy' to view.

📍 Local observability data:
   • Logs: Check your terminal output - Logger BB writes structured JSON to stdout
   • Metrics: Metrics BB writes EMF-formatted JSON to stdout (visible in terminal)
   • Traces: Tracer stores mock traces to .bb-data/ and logs them to stdout
```

## 缩放成本( C)

-   **自由等级 :** 最多3个仪表板,每台50公分
-   **超过自由级 :** 3美元/贴板/月
-   **无运行时间成本 :** 盘片为静态只读视图
-   **请求时没有 API 呼叫**

## 命名空间分辨率

度量衡命名空间来自度量衡 BB `namespace` 属性. Metrics BB从它的选项(说明 `namespace` 或退入范围 `fullId`) (中文(简体) ).

```typescript
const metrics = new Metrics(scope, 'metrics', { namespace: 'MyApp/Orders' });
const dashboard = new Dashboard(scope, 'dashboard', { metrics });
// Dashboard uses 'MyApp/Orders' as the CloudWatch namespace
```

## 默认尺寸

当一个度量衡BB有 `defaultDimensions` 配置, Dashboard 自动包含 部件查询中的这些维度。 这将确保部件瞄准相同的维度度度度 运行时发出的流。 维度 `MetricConfig` 在顶端合并 (在冲突上胜负).

```typescript
const metrics = new Metrics(scope, 'metrics', {
  namespace: 'MyApp/Orders',
  defaultDimensions: { service: 'orders', env: 'prod' },
});

const dashboard = new Dashboard(scope, 'dashboard', {
  metrics: {
    metrics,
    metricConfigs: [
      { name: 'OrdersPlaced' },  // queries with { service: 'orders', env: 'prod' }
      { name: 'Latency', dimensions: { endpoint: '/api' } },  // { service: 'orders', env: 'prod', endpoint: '/api' }
    ],
  },
});
```

## 常见问题

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

自动生成 Cloud Watch Dashboard 用于应用可观察性\.

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

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

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

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

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

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

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

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

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

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

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

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