AWS SDK for JavaScript (v3) 操作 Amazon CloudWatch 完整实战指南

• 示例工程
• 教程
• 后端

导读

本文基于 AWS 官方代码示例仓库（aws-doc-sdk-examples）中javascriptv3/example_code/cloudwatch目录下的完整示例集，系统讲解如何使用 AWS SDK for JavaScript (v3) 调用 Amazon CloudWatch 服务。CloudWatch 提供可靠、可扩展且灵活的资源监控方案，几分钟内即可投入使用。读完本文，你将掌握指标发布（PutMetricData）、告警生命周期管理（创建、列出、启用/停用、删除）、告警静默规则（Alarm Mute Rule）的创建与查询，以及 OTel 数据富集等核心操作的完整代码实现与运行方式。

示例集概览与目录结构

该示例集位于仓库的javascriptv3/example_code/cloudwatch/目录，遵循官方示例仓库的规范化结构，包含四类文件：

所有示例代码采用 ECMAScript 6（ES6）语法编写，以 ESM 模块形式导入 SDK，并通过type: "module"在package.json中声明。

环境准备（Prerequisites）

运行本目录示例前，需要先完成javascriptv3根目录下 README 中列出的前置条件，主要包括：

• 安装并配置 AWS SDK for JavaScript (v3) 所需的 AWS 凭证（Access Key / IAM 角色）；
• 安装 Node.js 运行时；
• 安装示例依赖（本目录依赖@aws-sdk/client-cloudwatch、@aws-sdk/client-ec2及@aws-doc-sdk-examples/lib）；
• 本地 AWS 区域应支持所用 API（并非所有 API 都在每个 AWS 区域经过测试）。

依赖清单与测试脚本

package.json声明了完整的依赖与脚本：

{ "name": "@aws-doc-sdk-examples/example-javascriptv3-cloudwatch", "type": "module", "dependencies": { "@aws-doc-sdk-examples/lib": "^1.0.0", "@aws-sdk/client-cloudwatch": "^3.1124.0", "@aws-sdk/client-ec2": "^3.213.0" }, "scripts": { "integration-test": "vitest run integration --reporter=junit --outputFile=test_results/cloudwatch-test-results.junit.xml" }, "devDependencies": { "uuid": "^9.0.0", "vitest": "^1.6.0" } }

其中@aws-sdk/client-cloudwatch提供 CloudWatch 客户端与全部命令类；@aws-sdk/client-ec2用于配合 EC2 相关指标与告警场景；集成测试通过 vitest 执行，并以 JUnit 格式输出结果。

客户端初始化与共享库

所有示例统一从libs/client.js导入共享的 CloudWatch 客户端实例：

import { CloudWatchClient } from "@aws-sdk/client-cloudwatch"; export const client = new CloudWatchClient({});

该文件位于 libs/client.js，通过无参数构造让 SDK 自动读取环境中的 AWS 凭证与区域配置。目录中还提供libs/cloudwatch-helper.js与libs/ec2-helper.js，用于封装测试与示例中复用的辅助逻辑。

单操作示例：完整 API 清单

README 列出的 15 个单操作覆盖了 CloudWatch 监控与告警的主要 API，按其功能可分为四组。

指标相关操作

发布自定义指标（PutMetricData）——actions/put-metric-data.js：

import { PutMetricDataCommand } from "@aws-sdk/client-cloudwatch"; import { client } from "../libs/client.js"; const run = async () => { const command = new PutMetricDataCommand({ MetricData: [ { MetricName: "PAGES_VISITED", Dimensions: [ { Name: "UNIQUE_PAGES", Value: "URLS", }, ], Unit: "None", Value: 1.0, }, ], Namespace: "SITE/TRAFFIC", }); try { return await client.send(command); } catch (err) { console.error(err); } }; export default run();

关键参数说明：

• Namespace：命名空间，建议用反斜杠分层，如SITE/TRAFFIC；
• MetricName：指标名称，如PAGES_VISITED；
• Dimensions：维度数组，每个维度由Name与Value组成，用于对指标进行细分；
• Unit：计量单位，此处为None；
• Value：指标数值。

列出指标（ListMetrics）——actions/list-metrics.js 按命名空间、指标名和维度过滤查询可用指标：

const command = new ListMetricsCommand({ Dimensions: [{ Name: "LogGroupName" }], MetricName: "IncomingLogEvents", Namespace: "AWS/Logs", }); const response = await client.send(command); console.log(`Metrics count: ${response.Metrics?.length}`);

该示例特别演示了CloudWatchServiceException的类型化错误捕获方式，并在isMain(import.meta.url)判断下实现"被导入时仅导出 main、直接运行时才执行"的双模式用法。

告警生命周期操作

创建告警（PutMetricAlarm）——actions/put-metric-alarm.js 创建当 EC2 实例 CPU 使用率超过 70% 持续 1 分钟即触发告警的规则：

const command = new PutMetricAlarmCommand({ AlarmName: process.env.CLOUDWATCH_ALARM_NAME, // 需设置为已存在的告警名称 ComparisonOperator: "GreaterThanThreshold", EvaluationPeriods: 1, MetricName: "CPUUtilization", Namespace: "AWS/EC2", Period: 60, Statistic: "Average", Threshold: 70.0, ActionsEnabled: false, AlarmDescription: "Alarm when server CPU exceeds 70%", Dimensions: [ { Name: "InstanceId", Value: process.env.EC2_INSTANCE_ID, // 需设置为已有的 EC2 实例 ID }, ], Unit: "Percent", });

参数语义：

• ComparisonOperator：比较运算符，如GreaterThanThreshold；
• EvaluationPeriods：评估周期数，此处为 1；
• Period：数据点聚合周期（秒），60 表示 1 分钟；
• Statistic：统计方法，如Average；
• Threshold：触发阈值；
• ActionsEnabled：是否启用告警动作（通知）；
• Dimensions：维度用于限定实例，如InstanceId。

启用 / 停用告警动作——actions/enable-alarm-actions.js 与 actions/disable-alarm-actions.js 分别通过EnableAlarmActionsCommand/DisableAlarmActionsCommand控制告警的AlarmNames列表（告警名由环境变量CLOUDWATCH_ALARM_NAME指定）：

const command = new EnableAlarmActionsCommand({ AlarmNames: [process.env.CLOUDWATCH_ALARM_NAME], });

const command = new DisableAlarmActionsCommand({ AlarmNames: process.env.CLOUDWATCH_ALARM_NAME, });

删除告警——actions/delete-alarms.js：

const command = new DeleteAlarmsCommand({ AlarmNames: [process.env.CLOUDWATCH_ALARM_NAME], });

查询告警状态——actions/describe-alarms.js 使用DescribeAlarmsForMetricCommand查询指定指标的告警，以及 actions/describe-alarm-contributors.js 查询告警贡献者。

告警静默规则（Alarm Mute Rule）操作

这是示例集中最具特色的一组 API。静默规则（Mute Rule）的作用是：在规则生效期间，被定向的告警仍持续评估、仍会在状态间流转，但不会触发已配置的动作——这是官方推荐的"已知维护窗口期抑制通知"方案，相比"先停用告警动作、再祈祷有人记得恢复"的做法更可靠。

创建 / 更新静默规则（PutAlarmMuteRule）——actions/put-alarm-mute-rule.js：

const command = new PutAlarmMuteRuleCommand({ Name: process.env.CLOUDWATCH_MUTE_RULE_NAME, Description: "Suppress checkout CPU pages during Sunday patching.", Rule: { Schedule: { // 周期性窗口使用五字段 cron 表达式，cron(Minutes Hours Day-of-month Month Day-of-week)。 // 注意是五个字段，不是 EventBridge 的六个字段。一次性窗口可用 at(2026-09-05T02:00) 这类 at 表达式。 Expression: "cron(0 2 * * SUN)", // 静默窗口激活后的持续时间，ISO 8601 时长格式，范围 PT1M（1 分钟）到 P15D（15 天）。 Duration: "PT2H", Timezone: "America/Los_Angeles", }, }, // 最多可按名称定向 100 个告警。省略 MuteTargets 表示静默账户内所有告警。 MuteTargets: { AlarmNames: [process.env.CLOUDWATCH_ALARM_NAME], }, });

参数细节：

• Schedule.Expression：支持五字段 cron（如cron(0 2 * * SUN)表示每周日 02:00）与 at 一次性表达式，注意与 EventBridge 六字段 cron 的区别；
• Schedule.Duration：ISO 8601 时长，合法范围PT1M到P15D；
• Schedule.Timezone：时区名称，如America/Los_Angeles；
• MuteTargets.AlarmNames：最多 100 个目标告警名，省略则静默全账户告警。

查询静默规则（GetAlarmMuteRule）——actions/get-alarm-mute-rule.js 返回规则完整配置，包括调度、目标告警以及当前状态（SCHEDULED、ACTIVE或EXPIRED）：

const command = new GetAlarmMuteRuleCommand({ AlarmMuteRuleName: process.env.CLOUDWATCH_MUTE_RULE_NAME, }); const response = await client.send(command); console.log(`Mute rule ${response.Name} is ${response.Status}.`);

列出静默规则（ListAlarmMuteRules）——actions/list-alarm-mute-rules.js 使用ListAlarmMuteRulesCommand分页列出账户中的静默规则。

删除静默规则（DeleteAlarmMuteRule）——actions/delete-alarm-mute-rule.js 使用DeleteAlarmMuteRuleCommand删除指定静默规则。

OTel 数据富集（OTel Enrichment）操作

CloudWatch 支持对 OpenTelemetry（OTel）遥测数据执行富集操作，示例集包含三个相关操作：

• StartOTelEnrichment——actions/start-otel-enrichment.js：启动 OTel 数据富集任务；
• StopOTelEnrichment——actions/stop-otel-enrichment.js：停止 OTel 数据富集任务；
• GetOTelEnrichment——actions/get-otel-enrichment.js：查询 OTel 富集任务状态。

运行方式

运行单操作

node ./actions/<fileName>

例如运行发布指标的示例：

node ./actions/put-metric-data.js

注意部分操作依赖环境变量（CLOUDWATCH_ALARM_NAME、CLOUDWATCH_MUTE_RULE_NAME、EC2_INSTANCE_ID），运行前需先通过export或.env方式设置对应值。

运行带命令行参数的示例

部分脚本支持通过命令行传入选项：

node ./scenarios/<fileName> --option1 --option2

选项解析基于 Node.js 内置的util.parseArgs，具体可用选项需查看对应脚本中的parseArgs用法说明。

ES6 / CommonJS 转换

所有示例均以 ECMAScript 6（ES6）编写。若项目使用 CommonJS 模块体系，可参考 AWS SDK for JavaScript v3 开发指南中关于 ES6/CommonJS 语法转换的说明进行改造，核心要点是将import改写为require，并调整默认导出方式。

集成测试

tests/目录提供了 8 个集成测试文件，覆盖全部核心 API 路径：

集成测试脚本由package.json中的integration-test声明，通过 vitest 执行并将结果输出为 JUnit 格式。集成测试会真实调用 AWS 服务，因此运行测试同样可能产生 AWS 账户费用。关于测试运行的整体说明，参见 javascriptv3 根目录 README。

费用与权限提醒

• 运行示例代码可能产生 AWS 账户费用，具体参考 AWS Pricing 与 Free Tier 说明；
• 运行测试同样可能产生费用；
• 强烈建议遵循最小权限原则（Least Privilege），仅授予完成当前任务所需的最低权限，不要使用管理员凭证运行示例；
• 本代码未在所有 AWS 区域逐一测试，使用前请确认目标 API 在所选区域的可用性。

进一步学习资源

• CloudWatch User Guide：CloudWatch 监控概念与使用指南；
• CloudWatch API Reference：各 API 的请求参数与响应结构；
• SDK for JavaScript (v3) CloudWatch reference：SDK 客户端与命令类的类型化参考。

结合本仓库中的源码，你可以直接以javascriptv3/example_code/cloudwatch/actions/下的示例为模板，快速搭建自定义的 CloudWatch 监控与告警自动化能力。

Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

SPDX-License-Identifier: Apache-2.0

• 示例工程
• 教程
• 后端