使用 AWS SDK for C 操作 Amazon CloudWatch完整示例代码实战指南【免费下载链接】aws-doc-sdk-examplesWelcome to the AWS Code Examples Repository. This repo contains code examples used in the AWS documentation, AWS SDK Developer Guides, and more. For more information, see the Readme.md file below.项目地址: https://gitcode.com/gh_mirrors/aw/aws-doc-sdk-examples本指南以仓库 cpp/example_code/cloudwatch 目录下的 CloudWatch 示例代码为核心系统讲解如何用 AWS SDK for C 完成指标上报、指标查询、告警生命周期管理、PromQL 告警、告警静默规则与 OpenTelemetry 富化等 15 个单动作Single Actions的编写、编译与运行方法。读完本文你将掌握该目录下每个示例的输入参数、调用链与构建测试流程能够直接在自己环境中复制运行。一、概述这套示例能做什么Amazon CloudWatch 提供了可靠、可扩展且灵活的可观测性监控方案开箱即用。本目录下的示例通过 AWS SDK for C依赖组件为monitoring、events、logs见 CMakeLists.txt演示了 CloudWatch 的三大能力域指标Metrics上报自定义指标数据、列出并过滤账户内指标告警Alarms创建、查询、启停、删除经典指标告警以及基于 PromQL 的告警进阶运维能力告警静默规则Mute Rule与 OpenTelemetry 指标富化OTel Enrichment。每个.cpp源文件都是一个独立、可直接编译成可执行文件的示例程序源码中以snippet-start/snippet-end标记的代码片段可直接嵌入 AWS 官方文档也是开发者学习 SDK API 用法的最佳入口。二、运行前准备Prerequisites2.1 SDK 环境安装在使用这些示例之前需先在本地完成 AWS SDK for C 的安装与配置官方流程见 AWS SDK for C 开发者指南的Getting started章节涵盖如何获取、构建 SDK并用一个 Hello World 风格的应用验证构建环境。随后参考Getting started with the AWS SDK for C code examples了解本仓库代码示例的组织结构与通用构建方式。2.2 IAM 权限要求运行本目录代码时你的 AWS 用户必须具备执行 Amazon CloudWatch 相关操作的权限。仓库文档建议直接使用 AWS 托管策略CloudWatchFullAccess批量授予所需权限通过 IAM 用户组附加策略的方式管理权限将策略附加到用户组再将用户加入组。需要强调的是示例程序会在你的 AWS 账户中真实创建、修改或删除 CloudWatch 资源如告警、静默规则因此运行会产生 AWS 费用测试同样可能产生费用。建议遵循最低权限原则least privilege只授予完成任务所需的最小权限并且本仓库代码未在所有 AWS 区域验证过请在使用前确认目标区域已支持相关功能。三、全部 15 个单动作示例速览单动作Single Actions指展示如何调用单个服务函数的代码片段。目录内每个示例对应一个源文件功能与入口函数位置如下示例文件功能main 函数put_metric_data.cpp上报自定义指标数据L24list_metrics.cpp列出并过滤指标L32put_metric_alarm.cpp创建经典指标告警L28put_promql_metric_alarm.cpp创建 PromQL 告警L43describe_alarms.cpp查询告警详情L27describe_alarm_contributors.cpp查询 PromQL 告警的贡献者L23enable_alarm_actions.cpp启用告警动作L83disable_alarm_actions.cpp禁用告警动作L28delete_alarm.cpp删除告警L25put_alarm_mute_rule.cpp创建/更新告警静默规则L33list_alarm_mute_rules.cpp列出告警静默规则L17get_alarm_mute_rule.cpp查询单条静默规则L20delete_alarm_mute_rule.cpp删除告警静默规则L19start_otel_enrichment.cpp开启 OTel 富化L35get_otel_enrichment.cpp查询 OTel 富化状态L15stop_otel_enrichment.cpp关闭 OTel 富化L18注README 的 Single actions 列表将 delete_alarm_mute_rule.cpp 与 delete_alarm.cpp 并列列出上表按文件整理为 16 个源文件其中 PutMetricAlarm 在put_metric_alarm.cpp与put_promql_metric_alarm.cpp中各有一次调用。所有示例遵循同一套 SDK 使用范式Aws::InitAPI(options)初始化 SDK → 构造Aws::CloudWatch::CloudWatchClient→ 构造 Request 对象设置参数 → 调用服务函数获取Outcome→ 用outcome.IsSuccess()判断成败并输出错误信息 →Aws::ShutdownAPI(options)清理。下面按功能域逐一展开。四、指标操作上报与查询4.1 上报自定义指标put_metric_dataput_metric_data.cpp 演示如何用PutMetricData提交一条自定义指标数据点模拟一个网站流量统计场景命名空间SITE/TRAFFIC指标PAGES_VISITED维度UNIQUE_PAGESURLSAws::CloudWatch::CloudWatchClient cw; Aws::CloudWatch::Model::Dimension dimension; dimension.SetName(UNIQUE_PAGES); dimension.SetValue(URLS); Aws::CloudWatch::Model::MetricDatum datum; datum.SetMetricName(PAGES_VISITED); datum.SetUnit(Aws::CloudWatch::Model::StandardUnit::None); datum.SetValue(data_point); datum.AddDimensions(dimension); Aws::CloudWatch::Model::PutMetricDataRequest request; request.SetNamespace(SITE/TRAFFIC); request.AddMetricData(datum); auto outcome cw.PutMetricData(request); if (!outcome.IsSuccess()) { std::cout Failed to put sample metric data: outcome.GetError().GetMessage() std::endl; } else { std::cout Successfully put sample metric data std::endl; }关键 API 说明SetNamespace指标命名空间用于逻辑分组如AWS/EC2是 AWS 服务指标命名空间自定义命名空间建议用SITE/TRAFFIC这类含斜杠的格式MetricDatum单条指标数据SetMetricName设置指标名SetValue设置数值SetUnit设置单位StandardUnit枚举此处为NoneAddDimensions维度是「名称值」对用于区分同一指标的不同序列例如按 URL 区分页面访问量一次请求可AddMetricData多条 datum批量上报。4.2 列出指标list_metricslist_metrics.cpp 演示ListMetrics的分页遍历与过滤。命令行最多可传两个可选参数metric_name与metric_namespace不传则列出全部Aws::CloudWatch::CloudWatchClient cw; Aws::CloudWatch::Model::ListMetricsRequest request; if (argc 1) request.SetMetricName(argv[1]); if (argc 2) request.SetNamespace(argv[2]); bool done false; bool header false; while (!done) { auto outcome cw.ListMetrics(request); if (!outcome.IsSuccess()) { std::cout Failed to list CloudWatch metrics: outcome.GetError().GetMessage() std::endl; break; } // 打印 MetricName / Namespace / 维度键值对 const auto metrics outcome.GetResult().GetMetrics(); for (const auto metric : metrics) { /* 输出格式化 */ } const auto next_token outcome.GetResult().GetNextToken(); request.SetNextToken(next_token); done next_token.empty(); }这段代码是CloudWatch SDK 分页模式的标准写法每次调用后从结果中取出GetNextToken()非空则回填到下一次请求继续拉取直到 token 为空从而完整遍历所有指标。五、经典指标告警全生命周期5.1 创建告警put_metric_alarmput_metric_alarm.cpp 演示基于 EC2 CPU 利用率创建经典指标告警。命令行参数alarm_name instance_idAws::CloudWatch::CloudWatchClient cw; Aws::CloudWatch::Model::PutMetricAlarmRequest request; request.SetAlarmName(alarm_name); request.SetComparisonOperator( Aws::CloudWatch::Model::ComparisonOperator::GreaterThanThreshold); request.SetEvaluationPeriods(1); request.SetMetricName(CPUUtilization); request.SetNamespace(AWS/EC2); request.SetPeriod(60); request.SetStatistic(Aws::CloudWatch::Model::Statistic::Average); request.SetThreshold(70.0); request.SetActionsEnabled(false); request.SetAlarmDescription(Alarm when server CPU exceeds 70%); request.SetUnit(Aws::CloudWatch::Model::StandardUnit::Seconds); Aws::CloudWatch::Model::Dimension dimension; dimension.SetName(InstanceId); dimension.SetValue(instanceId); request.AddDimensions(dimension); auto outcome cw.PutMetricAlarm(request);各字段含义经典告警的完整配置要素参数取值示例说明SetAlarmName自定义字符串告警名称账户内唯一SetComparisonOperatorGreaterThanThreshold比较运算符还有LessThanThreshold、GreaterThanOrEqualToThreshold、LessThanOrEqualToThreshold等SetEvaluationPeriods1触发告警所需的评估周期数SetMetricName/SetNamespaceCPUUtilization/AWS/EC2监控的指标与命名空间SetPeriod60评估周期秒数10 的倍数60~86400SetStatisticAverage统计方式Average/Sum/Minimum/Maximum/SampleCountSetThreshold70.0阈值SetActionsEnabledfalse是否启用告警动作默认关闭SetAlarmDescription描述文本告警说明AddDimensionsInstanceId实例ID按实例维度细化监控对象5.2 查询告警describe_alarmsdescribe_alarms.cpp 演示用DescribeAlarms分页列出所有指标告警输出每个告警的名称Name、ARN、描述Description与最近更新时间LastUpdatedrequest.SetMaxRecords(1); // 每页最多返回 1 条用于演示分页 while (!done) { auto outcome cw.DescribeAlarms(request); const auto alarms outcome.GetResult().GetMetricAlarms(); for (const auto alarm : alarms) { std::cout std::left std::setw(32) alarm.GetAlarmName() std::setw(64) alarm.GetAlarmArn() std::setw(64) alarm.GetAlarmDescription() std::setw(20) alarm.GetAlarmConfigurationUpdatedTimestamp() .ToGmtString(SIMPLE_DATE_FORMAT_STR) std::endl; } const auto next_token outcome.GetResult().GetNextToken(); request.SetNextToken(next_token); done next_token.empty(); }值得注意的实现细节SetMaxRecords(1)刻意把每页结果压到最小用于演示NextToken 分页循环的正确性——这是 CloudWatch 查询类 API 的通用手法与list_metrics.cpp一致时间字段通过GetAlarmConfigurationUpdatedTimestamp().ToGmtString(%Y-%m-%d)格式化为 GMT 日期字符串本示例无需命令行参数直接运行即可。5.3 启用 / 禁用告警动作enable_alarm_actions.cpp源码演示了「创建带动作的告警 启用动作」的完整流程命令行参数alarm_name instance_id alarm_action_arn// 1) 创建告警除常规字段外通过 AddAlarmActions 绑定动作 ARN request.AddAlarmActions(actionArn); auto outcome cw.PutMetricAlarm(request); // 2) 启用该告警的动作 Aws::CloudWatch::Model::EnableAlarmActionsRequest enable_request; enable_request.AddAlarmNames(alarm_name); auto enable_outcome cw.EnableAlarmActions(enable_request);动作 ARN 通常是 SNS 主题或 Auto Scaling 策略的 ARN当告警进入 ALARM 状态时会触发这些动作。注意创建时SetActionsEnabled(false)随后显式调用EnableAlarmActions完成启用。disable_alarm_actions.cpp源码是上述过程的逆操作命令行参数alarm_name。核心调用仅两步Aws::CloudWatch::Model::DisableAlarmActionsRequest disableAlarmActionsRequest; disableAlarmActionsRequest.AddAlarmNames(alarm_name); auto disableAlarmActionsOutcome cw.DisableAlarmActions(disableAlarmActionsRequest);5.4 删除告警delete_alarmdelete_alarm.cpp 演示用DeleteAlarms删除告警命令行参数alarm_nameAws::CloudWatch::CloudWatchClient cw; Aws::CloudWatch::Model::DeleteAlarmsRequest request; request.AddAlarmNames(alarm_name); // AddAlarmNames 支持一次删除多个告警 auto outcome cw.DeleteAlarms(request);DeleteAlarmsRequest内部是告警名列表因此批量删除只需多次调用AddAlarmNames。六、PromQL 告警基于查询的下一代告警6.1 与传统告警的区别put_promql_metric_alarm.cpp 演示如何创建基于 PromQL 查询的告警。这类告警与传统指标告警有本质差异源码注释L8-L18给出了精确定义查询可同时匹配多个时间序列每个匹配的序列被独立跟踪为一个贡献者contributor不再统计“连续越界周期数”而是指定时长贡献者连续越界达到pending 时长后进入ALARM停止越界达到recovery 时长后回到OKPromQL 告警初始状态为OK而非经典告警的INSUFFICIENT_DATAEvaluationCriteria与经典字段互斥使用它时必须同时设置EvaluationInterval且不得设置Period、Statistic、Threshold、ComparisonOperator、EvaluationPeriods、DatapointsToAlarm、TreatMissingData。6.2 代码实现命令行参数alarm_name query其中比较条件要写在 PromQL 查询本身里如avg(cpu_usage) 80没有单独的阈值字段Aws::CloudWatch::Model::AlarmPromQLCriteria promQLCriteria; promQLCriteria.SetQuery(query); promQLCriteria.SetPendingPeriod(300); // 连续越界 300 秒进入 ALARM promQLCriteria.SetRecoveryPeriod(120); // 停止越界 120 秒回到 OK Aws::CloudWatch::Model::EvaluationCriteria evaluationCriteria; evaluationCriteria.SetPromQLCriteria(promQLCriteria); Aws::CloudWatch::Model::PutMetricAlarmRequest request; request.SetAlarmName(alarm_name); request.SetAlarmDescription(A PromQL alarm created by the AWS SDK for C.); request.SetEvaluationCriteria(evaluationCriteria); request.SetEvaluationInterval(30); // 合法值10、20、30以及 60 的任意倍数上限 3600 auto outcome cw.PutMetricAlarm(request);运行前提账户中需要有 OpenTelemetry 指标流入且若查询依赖富化标签需先开启 OTel 富化见第八节。6.3 查询贡献者describe_alarm_contributorsdescribe_alarm_contributors.cppDescribeAlarmContributorsmain 函数在 L23用于列出 PromQL 告警当前每个贡献者匹配查询的时间序列的状态是运维 PromQL 告警时的排查工具。七、告警静默规则Alarm Mute Rule7.1 为什么需要静默规则put_alarm_mute_rule.cpp 源码注释L8-L11解释了其价值静默规则生效期间目标告警照常评估、照常状态迁移但已配置的动作不会触发。这是已知维护窗口内抑制通知的官方推荐方式——比“禁用告警动作后靠人记得重新启用”要可靠得多。7.2 创建静默规则命令行参数mute_rule_name alarm_name// 周期窗口用五字段 cron 表达式cron(Minutes Hours Day-of-month Month Day-of-week) // 注意是五字段不是 EventBridge 的六字段一次性窗口可用 at(2026-09-05T02:00) Aws::CloudWatch::Model::Schedule schedule; schedule.SetExpression(cron(0 2 * * SUN)); schedule.SetDuration(PT2H); // ISO 8601 时长范围 PT1M1 分钟~ P15D15 天 schedule.SetTimezone(America/Los_Angeles); Aws::CloudWatch::Model::Rule rule; rule.SetSchedule(schedule); // 最多目标 100 个告警若不设置 MuteTargets规则作用于账户内所有告警 Aws::CloudWatch::Model::MuteTargets muteTargets; muteTargets.AddAlarmNames(alarm_name); Aws::CloudWatch::Model::PutAlarmMuteRuleRequest request; request.SetName(mute_rule_name); request.SetDescription(A mute rule created by the AWS SDK for C.); request.SetRule(rule); request.SetMuteTargets(muteTargets); auto outcome cw.PutAlarmMuteRule(request);配置要点来自源码注释均为可直接使用的取值范围cron 表达式仅5 个字段分钟 小时 日 月 星期与 EventBridge 的 6 字段不同不要混淆示例cron(0 2 * * SUN)表示每周日凌晨 2:00 生效at 表达式一次性窗口格式如at(2026-09-05T02:00)DurationISO 8601 时长格式合法范围PT1M1 分钟到P15D15 天示例PT2H为 2 小时TimezoneIANA 时区名如America/Los_AngelesMuteTargets最多 100 个告警留空则全局静默所有告警需谨慎使用。7.3 查询与删除静默规则配套示例同样遵循标准 SDK 模式list_alarm_mute_rules.cppListAlarmMuteRulesmain 函数 L17分页列出账户内全部静默规则get_alarm_mute_rule.cppGetAlarmMuteRulemain 函数 L20按规则名查询单条规则详情delete_alarm_mute_rule.cppDeleteAlarmMuteRulemain 函数 L19删除指定静默规则维护窗口结束后即可清理。八、OpenTelemetry 富化让 vended 指标可被 PromQL 查询8.1 富化解决什么问题start_otel_enrichment.cpp 演示如何为账户开启 OpenTelemetry 富化StartOTelEnrichment使得CloudWatch vended 指标如带InstanceId维度的 EC2CPUUtilization指标被自动装饰上资源 ARN 与资源标签标签从而可以被 PromQL 按资源标签过滤查询。8.2 开启富化该示例无需命令行参数核心调用非常简洁Aws::Client::ClientConfiguration clientConfig; // Optional: Set to the AWS Region (overrides config file). // clientConfig.region us-east-1; Aws::CloudWatch::CloudWatchClient cw(clientConfig); Aws::CloudWatch::Model::StartOTelEnrichmentRequest request; auto outcome cw.StartOTelEnrichment(request);运行前提账户必须已启用Resource tags on telemetry遥测资源标签。注意一个容易混淆的点——OTLP 指标摄入并不是 AWS SDK 操作要把 OpenTelemetry 指标送入 CloudWatch需要将 OpenTelemetry Collector 或 AWS Distro for OpenTelemetry (ADOT) 指向 CloudWatch 的 OTLP 指标端点https://monitoring.region.amazonaws.com/v1/metrics而富化开关才走 SDK API。8.3 查询与关闭富化get_otel_enrichment.cppGetOTelEnrichmentmain 函数 L15查询当前账户的富化开启状态stop_otel_enrichment.cppStopOTelEnrichmentmain 函数 L18关闭富化与开启过程对称同样无需参数。九、构建与运行示例9.1 构建规则CMake本目录通过 CMakeLists.txt 统一构建关键点CMake 最低版本 3.13默认BUILD_SHARED_LIBSON共享库CMAKE_CXX_STANDARD 11通过find_package(AWSSDK REQUIRED COMPONENTS monitoring events logs)拉取 SDK 的monitoringCloudWatch 核心、events、logs三个组件L13-L14、L40构建脚本用file(GLOB *.cpp)收集目录内全部源文件为每个源文件生成名为run_源文件名的可执行目标如run_put_metric_data、run_put_promql_metric_alarm并注入SOURCE_DIR编译宏L56-L78支持通过命令行定义AWSDOC_SOURCE变量只构建指定文件L54-L60便于单独调试某个示例。9.2 运行单个示例每个源文件都会在构建目录中生成对应的可执行文件命名规则为run_ 源文件名去掉后缀。在 build 目录下直接运行即可程序会打印所需参数cd BUILD_DIR ./run_put_metric_data 42 ./run_put_metric_alarm my-alarm i-0123456789abcdef0 ./run_enable_alarm_actions my-alarm i-0123456789abcdef0 arn:aws:sns:... ./run_put_promql_metric_alarm my-promql-alarm avg(cpu_usage) 80 ./run_put_alarm_mute_rule my-mute-rule my-alarm ./run_list_metrics ./run_list_metrics CPUUtilization AWS/EC2 ./run_describe_alarms参数不符时程序会打印Usage:提示并返回退出码 1。各示例所需参数详见前文各节及源码头部注释。若源文件位于其他子目录请参见该目录内的 README。9.3 运行测试本目录支持 CTest 自动化测试。运行测试同样可能产生 AWS 费用。在 build 目录中执行cd BUILD_DIR cmake path-to-root-of-this-source-code -DBUILD_TESTSON make ctestBUILD_TESTSON会启用 CMakeLists.txt 中的include(CTest)逻辑将测试注册到 CTest 中。十、额外学习资源CloudWatch User Guide监控、告警、日志、指标的基础概念与操作指南CloudWatch API Reference各操作的请求/响应结构与错误码权威定义AWS SDK for C CloudWatch 参考aws-cpp-sdk-monitoring包CloudWatchClient、各 Request/Result 模型的 C API 文档。结合本目录 16 个可编译示例你可以覆盖「采集PutMetricData→ 观测ListMetrics/DescribeAlarms→ 告警经典 PromQL→ 抑制Mute Rule→ 观测增强OTel Enrichment」的完整 CloudWatch 运维闭环。Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.SPDX-License-Identifier: Apache-2.0【免费下载链接】aws-doc-sdk-examplesWelcome to the AWS Code Examples Repository. This repo contains code examples used in the AWS documentation, AWS SDK Developer Guides, and more. For more information, see the Readme.md file below.项目地址: https://gitcode.com/gh_mirrors/aw/aws-doc-sdk-examples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考