# @aws-cdk/aws-cloudwatch 中文文档

规范地址：https://npmcn.com/package/%40aws-cdk/aws-cloudwatch/

版本：1\.204\.0
npm 元数据更新时间：2023-11-21T10:14:14.539Z
中文译文更新时间：2026-11-07T09:17:33.170Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aws-cdk/aws-cloudwatch
原文对照：https://npmcn.com/package/%40aws-cdk/aws-cloudwatch/?lang=original
项目主页：https://github.com/aws/aws-cdk
源码仓库：https://github.com/aws/aws-cdk

弃用说明：AWS CDK v1 has reached End-of-Support on 2023-06-01\. This package is no longer being updated, and users should migrate to AWS CDK v2\. For more information on how to migrate, see https://docs\.aws\.amazon\.com/cdk/v2/guide/migrating-v2\.html

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

- 包体积（解压后）：1.9 MB，55 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 14\.15\.0
- 运行依赖：3 个
- peer 依赖：@aws-cdk/aws-iam 1\.204\.0，@aws-cdk/core 1\.204\.0，constructs ^3\.3\.69
- 首次发布：2018-07-31T13:30:21.956Z
- 最新版本发布：2023-06-19T21:05:23.041Z
- 近 30 天下载量：403676（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：288（近 12 个月 0 个）

## 中文简介

AWS: Cloud Watch 的 CDK 构建库

## 安装

```sh
npm install @aws-cdk/aws-cloudwatch
```

也可以使用：`pnpm add @aws-cdk/aws-cloudwatch`、`yarn add @aws-cdk/aws-cloudwatch`、`bun add @aws-cdk/aws-cloudwatch`

## README

# 亚马逊云表构建库

* * *

![End-of-Support](https://img.shields.io/badge/End--of--Support-critical.svg?style=for-the-badge)

> AWS CDK v1在2023-06-01上达到了支持结束. 此软件包不再更新,用户应该迁移到 AWS CDK v2.
> 
> 关于如何移徙的更多信息,请参见: [_移动到 AWS CDK v2_ 指南](https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html)。 。 。 .

* * *

## 计量对象

计量对象代表由AWS服务或您自己发射的度量衡 应用程序,例如 `CPUUsage`, (中文(简体) ), `FailureCount` 或者说 `Bandwidth`。 。 。 .

计量对象可以直接构建或被资源所暴露为 属性。 显示度量衡的资源将具有可查看的功能 喜欢 `metricXxx()` 它将返回带有默认的已初始化的计量对象 这有道理.

譬如说, `lambda.Function` 对象有: `fn.metricErrors()` 方法,哪个 表示 Lambda 函数报告的错误量 :

```ts
declare const fn: lambda.Function;

const errors = fn.metricErrors();
```

`Metric` 对象可以是账户,也可以是区域。 您可以指定 `account` 财务报告和审定财务报表 `region` 作为度量的属性,或使用 `metric.attachTo(Construct)` 方法. `metric.attachTo()` 将自动复制 `region` 财务报告和审定财务报表 `account` 区域 `Construct`,可以来自构造树的任何地方.

你也可以即兴表演 `Metric` 用于引用的任何对象 [已公布的衡量标准](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/aws-services-cloudwatch-metrics.html) 在CDK构造上没有使用方便方法曝光. 例如:

```ts
const hostedZone = new route53.HostedZone(this, 'MyHostedZone', { zoneName: "example.org" });
const metric = new cloudwatch.Metric({
  namespace: 'AWS/Route53',
  metricName: 'DNSQueries',
  dimensionsMap: {
    HostedZoneId: hostedZone.hostedZoneId
  }
});
```

### 证明一个新的计量对象

如果你想参考一个尚未被现有构造所暴露的度量衡, 你可以即兴表演 `Metric` 用于代表它。 例如:

```ts
const metric = new cloudwatch.Metric({
  namespace: 'MyNamespace',
  metricName: 'MyMetric',
  dimensionsMap: {
    ProcessingStep: 'Download'
  }
});
```

### 计量数学

数学表达式通过即时 `MathExpression` 课. 例如,一个将另外两个度量的数学表达式看起来是这样的:

```ts
declare const fn: lambda.Function;

const allProblems = new cloudwatch.MathExpression({
  expression: "errors + throttles",
  usingMetrics: {
    errors: fn.metricErrors(),
    faults: fn.metricThrottles(),
  }
});
```

你用得着 `MathExpression` 类似任何其他度量衡的对象,包括使用 它们在其他数学表达式中:

```ts
declare const fn: lambda.Function;
declare const allProblems: cloudwatch.MathExpression;

const problemPercentage = new cloudwatch.MathExpression({
  expression: "(problems / invocations) * 100",
  usingMetrics: {
    problems: allProblems,
    invocations: fn.metricInvocations()
  }
});
```

### 搜索表达式

数学表达式也支持搜索表达式. 例如,以下内容: 搜索表达式返回它找到的所有 CPUUUtili化 度量衡,并带有 显示平均统计的图表,汇总时间为5分钟:

```ts
const cpuUtilization = new cloudwatch.MathExpression({
  expression: "SEARCH('{AWS/EC2,InstanceId} MetricName=\"CPUUtilization\"', 'Average', 300)",

  // Specifying '' as the label suppresses the default behavior
  // of using the expression as metric label. This is especially appropriate
  // when using expressions that return multiple time series (like SEARCH()
  // or METRICS()), to show the labels of the retrieved metrics only.
  label: '',
});
```

跨账户和跨区域搜索表达式也得到了支持. 使用 页:1 `searchAccount` 财务报告和审定财务报表 `searchRegion` 要指定账户的属性 和/或区域对搜索表达式进行评价.

### 合计

要图解或提醒测量值, 您必须先用函数组合它们 喜欢 `Average` 或百分位函数像 `P99`。默认情况下,大多数计量对象 由 CDK 库返回的将配置为 `Average` 结束 `300 seconds` (5分钟). 例外是,如果该度量值代表了一系列离散事件,例如: 失败。 在这种情况下,计量对象将被配置为 `Sum` 结束 `300 seconds`,即它代表了该事件发生在 时间段.

如果您想要更改 Metric 对象的默认集合( 例如, ), 函数或周期,您可以通过通过附加参数来实现 至度量函数调用:

```ts
declare const fn: lambda.Function;

const minuteErrorRate = fn.metricErrors({
  statistic: 'avg',
  period: Duration.minutes(1),
  label: 'Lambda failure rate'
});
```

此函数还允许更改公尺标签或颜色( 这将是 插入图表时有用,见下文.

> 比率对和数
> 
> 使用原因 `Sum` 计算离散事件是 _有点_ 事件为 以任一方式发射 `0` 或者说 `1` (例如 `Errors` 和一些是 仅以 `1` (例如 `NumberOfMessagesPublished` 用于SNS 专题).
> 
> 以防万一 `0`\- 量子被射出, 它有道理采取 `Average` 这其中 衡量标准:结果将是所有处决的错误的一小部分.
> 
> 若为 `0`\- 度量衡没有释放 `Average` 永远等于 `1`, (中文(简体) ), 也没什么用.
> 
> 为了简化心理模式 `Metric` 对象,我们默认为 使用汇总 `Sum`,这两个指标类型将相同。 狦 恰好知道您想要提醒的量子 以速率计算是合理的 (单位:千美元)`Average`)你总是可以选择改变统计.

### 标签

度量衡标签在包含度量衡的图形传说中被显示.

你用得着 [动态标签](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph-dynamic-labels.html) 显示关于显示的时间序列的汇总信息 在传说中。 例如,如果使用:

```ts
declare const fn: lambda.Function;

const minuteErrorRate = fn.metricErrors({
  statistic: 'sum',
  period: Duration.hours(1),

  // Show the maximum hourly error count in the legend
  label: '[max: ${MAX}] Lambda failure rate',
});
```

作为参数标签,可见范围内的最大值将 在图例中的时间序列名称旁边显示.

如果计量是一个数学表达式,产生一个以上的时间序列,则 最大值将逐个计算并显示每个时间序列的产量 通过数学表达式.

## 警报

警报可以通过两种方式之一在度量上生成. 创建一个 `Alarm` 对象,通过 `Metric` 将提醒设置在 :

```ts
declare const fn: lambda.Function;

new cloudwatch.Alarm(this, 'Alarm', {
  metric: fn.metricErrors(),
  threshold: 100,
  evaluationPeriods: 2,
});
```

或者,你可以打电话 `metric.createAlarm()`数字 :

```ts
declare const fn: lambda.Function;

fn.metricErrors().createAlarm(this, 'Alarm', {
  threshold: 100,
  evaluationPeriods: 2,
});
```

创建提醒时要设置的最重要属性是:

-   `threshold`: 比较度量衡的值.
-   `comparisonOperator`: 用于比较操作,默认为 `metric >= threshold`。 。 。 .
-   `evaluationPeriods`: 衡量尺度必须连续多少个周期 突破触发警报的门槛.

要创建交叉账户提醒, 请确定您已启用 [交叉账户功能](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Cross-Account-Cross-Region.html) 在云层观察。 然后,设置 `account` 属性 `Metric` 手动或通过 `metric.attachTo()` 方法.

### 提醒动作

要将动作添加到提醒中, 请使用来自 `@aws-cdk/aws-cloudwatch-actions` 软件包。 例如,向 当警报中断时, SNS 主题如下:

```ts
import * as cw_actions from '@aws-cdk/aws-cloudwatch-actions';
declare const alarm: cloudwatch.Alarm;

const topic = new sns.Topic(this, 'Topic');
alarm.addAlarmAction(new cw_actions.SnsAction(topic));
```

#### 通知格式

提醒可以在两个"格式"中创建一个:

-   有"顶级参数"(这些是"云表警报"的经典风格).
-   并有一份测量规格清单(这些是"云表警报"的现代风格).

对于后向兼容性, CDK 将尝试创建经典的顶级 Cloud Watch 提醒 尽可能多,除非您正在使用无法以该格式表达的特性. 需要新式提醒格式的特征有:

-   计算数学
-   交叉计量
-   标签

两者的区别并不影响提醒的功能 无论如何, _除外_ 提醒生成的通知格式为 他们之间不同 这影响到通过SNS发出的通知, 以及这个警报引发的事件 如果你在写 输入这些通知的代码, 确保处理两种格式.

### 综合警报

[综合警报](https://aws.amazon.com/about-aws/whats-new/2020/03/amazon-cloudwatch-now-allows-you-to-combine-multiple-alarms/) 可以从现有的提醒资源中创建.

```ts
declare const alarm1: cloudwatch.Alarm;
declare const alarm2: cloudwatch.Alarm;
declare const alarm3: cloudwatch.Alarm;
declare const alarm4: cloudwatch.Alarm;

const alarmRule = cloudwatch.AlarmRule.anyOf(
  cloudwatch.AlarmRule.allOf(
    cloudwatch.AlarmRule.anyOf(
      alarm1,
      cloudwatch.AlarmRule.fromAlarm(alarm2, cloudwatch.AlarmState.OK),
      alarm3,
    ),
    cloudwatch.AlarmRule.not(cloudwatch.AlarmRule.fromAlarm(alarm4, cloudwatch.AlarmState.INSUFFICIENT_DATA)),
  ),
  cloudwatch.AlarmRule.fromBoolean(false),
);

new cloudwatch.CompositeAlarm(this, 'MyAwesomeCompositeAlarm', {
  alarmRule,
});
```

### 关于单位的说明

在 " 云表 " 中,计量基准与单位一起排放,如 `seconds` 或者说 `bytes`时 `Metric` 对象为 `unit` 属性,将用来 _过滤器_ 用同一种方法排放的基线数据流 `unit` 属性.

特别是 `unit` 字段为 _没有_ 用于调整基准或提醒阈值 值(例如,它不能用于在 _兆字节_ 如果公尺流作为 _字节_) (中文(简体) ).

你几乎肯定不想说明 `unit` 创建时的属性 `Metric` 对象(它将检索所有数据,而不论其单位), 除非你有非常具体的要求。 注意,无论如何,云表 只支持过滤 `unit` 用于提醒,而不是在 Dashboard 图形.

关于实际单位的讨论,请参见以下 GitHub 问题 cDK中的计算 : [https://github.com/aws/aws-cdk/issues/5595 (英语)](https://github.com/aws/aws-cdk/issues/5595)

## 盘子

Dashboard 是存储在服务器侧的部件,可以快速访问 从AWS控制台。 可用的部件是一段时间以来一个度量的图表 参数的当前值,或 Markdown 的静态块来解释 图表的意思.

以下部件可供使用:

-   `GraphWidget` - 显示左右两侧的任何度量衡 竖轴.
-   `AlarmWidget` -- 显示单个提醒的图表和提醒行 .
-   `SingleValueWidget` -- 显示一组计量的当前值.
-   `TextWidget` 显示一些静态的Markdown.
-   `AlarmStatusWidget` -- 显示您在网格视图中的提醒状态 .

### 图形部件

图形元件可以在任意一个 `left` 或者说 `right` 垂直轴 :

```ts
declare const dashboard: cloudwatch.Dashboard;
declare const executionCountMetric: cloudwatch.Metric;
declare const errorCountMetric: cloudwatch.Metric;

dashboard.addWidgets(new cloudwatch.GraphWidget({
  title: "Executions vs error rate",

  left: [executionCountMetric],

  right: [errorCountMetric.with({
    statistic: "average",
    label: "Error rate",
    color: cloudwatch.Color.GREEN,
  })]
}));
```

使用方法 `addLeftMetric()` 财务报告和审定财务报表 `addRightMetric()` 您可以在以后的图形部件中添加参数.

图形部件也可以显示左侧或右Y轴所附加的注释.

```ts
declare const dashboard: cloudwatch.Dashboard;

dashboard.addWidgets(new cloudwatch.GraphWidget({
  // ...

  leftAnnotations: [
    { value: 1800, label: Duration.minutes(30).toHumanString(), color: cloudwatch.Color.RED, },
    { value: 3600, label: '1 hour', color: '#2ca02c', }
  ],
}));
```

图形图例可以从部件底部的默认位置来调整 .

```ts
declare const dashboard: cloudwatch.Dashboard;

dashboard.addWidgets(new cloudwatch.GraphWidget({
  // ...

  legendPosition: cloudwatch.LegendPosition.RIGHT,
}));
```

该图可以在尚未完全汇总的最后一分钟内发布活数据.

```ts
declare const dashboard: cloudwatch.Dashboard;

dashboard.addWidgets(new cloudwatch.GraphWidget({
  // ...

  liveData: true,
}));
```

图视图可以从默认的"timeSeries"改为"bar"或"pie".

```ts
declare const dashboard: cloudwatch.Dashboard;

dashboard.addWidgets(new cloudwatch.GraphWidget({
  // ...

  view: cloudwatch.GraphWidgetView.BAR,
}));
```

### 提醒部件

提醒部件显示单个提醒的图形和提醒行 :

```ts
declare const dashboard: cloudwatch.Dashboard;
declare const errorAlarm: cloudwatch.Alarm;

dashboard.addWidgets(new cloudwatch.AlarmWidget({
  title: "Errors",
  alarm: errorAlarm,
}));
```

### 单值部件

单值部件显示一组度量标准的最新值(相反) 改为随时间推移的数值图:

```ts
declare const dashboard: cloudwatch.Dashboard;
declare const visitorCount: cloudwatch.Metric;
declare const purchaseCount: cloudwatch.Metric;

dashboard.addWidgets(new cloudwatch.SingleValueWidget({
  metrics: [visitorCount, purchaseCount],
}));
```

在四舍五入前显示尽可能多的数字.

```ts
declare const dashboard: cloudwatch.Dashboard;

dashboard.addWidgets(new cloudwatch.SingleValueWidget({
  metrics: [ /* ... */ ],

  fullPrecision: true,
}));
```

### 文本部件

一个文本部件显示 MarkDown 的任意一块 。 用此来添加解释 到您的仪表板:

```ts
declare const dashboard: cloudwatch.Dashboard;

dashboard.addWidgets(new cloudwatch.TextWidget({
  markdown: '# Key Performance Indicators'
}));
```

### 提醒状态部件

提醒状态部件立即显示任何类型提醒的状态并给出 能够将一个或多个警报集合到一个小表面.

```ts
declare const dashboard: cloudwatch.Dashboard;
declare const errorAlarm: cloudwatch.Alarm;

dashboard.addWidgets(
  new cloudwatch.AlarmStatusWidget({
    alarms: [errorAlarm],
  })
);
```

提醒状态部件仅显示点火提醒, 按状态和时间戳排序 :

```ts
declare const dashboard: cloudwatch.Dashboard;
declare const errorAlarm: cloudwatch.Alarm;

dashboard.addWidgets(new cloudwatch.AlarmStatusWidget({
  title: "Errors",
  alarms: [errorAlarm],
  sortBy: cloudwatch.AlarmStatusWidgetSortBy.STATE_UPDATED_TIMESTAMP,
  states: [cloudwatch.AlarmState.ALARM],
}));
```

### 查询结果部件

A 类 `LogQueryWidget` 显示 Logs Insights 查询的结果 :

```ts
declare const dashboard: cloudwatch.Dashboard;

dashboard.addWidgets(new cloudwatch.LogQueryWidget({
  logGroupNames: ['my-log-group'],
  view: cloudwatch.LogQueryVisualizationType.TABLE,
  // The lines will be automatically combined using '\n|'.
  queryLines: [
    'fields @message',
    'filter @message like /Error/',
  ]
}));
```

### 自定义部件

A 类 `CustomWidget` 显示 AWS Lambda 函数的结果 :

```ts
declare const dashboard: cloudwatch.Dashboard;

// Import or create a lambda function
const fn = lambda.Function.fromFunctionArn(
  dashboard,
  'Function',
  'arn:aws:lambda:us-east-1:123456789012:function:MyFn',
);

dashboard.addWidgets(new cloudwatch.CustomWidget({
  functionArn: fn.functionArn,
  title: 'My lambda baked widget',
}));
```

您可以在 [亚马逊云表用户指南](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/add_custom_widget_dashboard.html)。 。 。 .

### 平面板布局

仪表盘上的部件被直观地放入24列的网格 宽度。 通常您指定 X 和 Y 坐标,用于 Dash 板上的部件, 但由于手动操作不方便,库中包含一个简单的 排版系统可以帮助您设置您想要的仪表板.

部件有一个 `width` 财务报告和审定财务报表 `height` 财产,将自动成为 横向或纵向堆放,以填写可用的 空间.

通过调用将部件添加到 Dashboard 中 `add(widget1, widget2, ...)`。 。 。 . 同一呼叫中给出的部件将横向排列. 给定部件 在不同的呼叫中,将垂直排列。 更复杂的布局, 您可以使用下列部件以不同方式将部件组合在一起:

-   `Column`:垂直堆放两个或多个部件.
-   `Row`: 水平显示两个或两个以上部件.
-   `Spacer`: 取出空格

## 常见问题

### @aws-cdk/aws-cloudwatch 是什么？

AWS: Cloud Watch 的 CDK 构建库注意：该包已被作者标记为弃用——AWS CDK v1 has reached End-of-Support on 2023-06-01\. This package is no longer being updated, and users should migrate to AWS CDK v2\. For more information on how to migrate, see https://docs\.aws\.amazon\.com/cdk/v2/guide/migrating-v2\.html

### 如何安装 @aws-cdk/aws-cloudwatch？

在项目目录运行 npm install @aws-cdk/aws-cloudwatch，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@aws-cdk/aws-iam（1\.204\.0）、@aws-cdk/core（1\.204\.0）、constructs（^3\.3\.69）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws-cdk/aws-cloudwatch 支持 TypeScript 吗？

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

### @aws-cdk/aws-cloudwatch 支持 ESM 还是 CommonJS？

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

### @aws-cdk/aws-cloudwatch 需要什么版本的 Node\.js？

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

### @aws-cdk/aws-cloudwatch 可以商用吗？

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

### @aws-cdk/aws-cloudwatch 的下载量有多少？

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

### @aws-cdk/aws-cloudwatch 还在维护吗？

最新版本 1\.204\.0 发布于 2023/06/20（3 年前）；至今共发布 288 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/07/31。作者已将其标记为弃用，新项目建议寻找替代方案。