面向 Amazon CloudWatch 控制面板的 API 和 CloudFormation 支持

我们在几年前发布了 CloudWatch 控制面板。在专为这次发布撰写的文章中，我介绍了如何以交互方式创建控制面板，以便以图形形式显示所选的 CloudWatch 指标。发布之后，我们增加了其他功能，包括全屏模式、深色主题、控制 Y 轴的范围、简化的重命名、持久性存储和新的可视化选项。

新 API 和 CLI

虽然控制台支持非常有利于交互式使用，但许多客户要求我们提供对控制面板及其中小部件的编程式创建和操作的支持。这些客户想要动态构建和维护控制面板，从而在创建和销毁相应的 AWS 资源时添加和删除小部件。其他客户则希望在两个或多个 AWS 账户中设置和维护一组一致的控制面板。

我非常高兴地宣布，面向 CloudWatch 控制面板的 API、CLI 和 AWS CloudFormation 支持现已推出，您可以立即开始使用！

我们新增了四个 API 函数 (和等效的 CLI 命令)：

[](http://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_ListDashboards.html "undefined") / aws cloudwatch list-dashboards – 用于提取账户内所有控制面板的列表，或共享通用前缀的子集。

[](http://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_GetDashboard.html "undefined") / aws cloudwatch get-dashboard – 用于提取单个控制面板的详细信息。

[](http://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutDashboard.html "undefined") / aws cloudwatch put-dashboard – 用于创建新控制面板或更新现有控制面板。

[](http://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_DeleteDashboards.html "undefined") / aws cloudwatch delete-dashboards – 用于删除一个或多个控制面板。

控制面板概念 我将要向您展示如何使用这些函数和命令。在转入正题之前，我应该介绍几个重要的控制面板概念和属性。

全局 – 控制面板是 AWS 账户的一部分，但未与特定 AWS 区域关联。每个账户最多可以包含 500 个控制面板。

命名 – 每个控制面板都有一个在 AWS 账户内唯一的名称。名称最长可达 255 个字符。

网格模式 – 每个控制面板都由网格单元格组成。网格包括 24 个单元格，高度可根据需要调整。控制面板中的每个小部件可位于一组特定的网格坐标上，大小可跨越一个整数的网格单元格。

小部件 (可视化) – 每个小部件可以显示文本或一组 CloudWatch 指标。文本通过 Markdown 指定；指标可以显示为单个值，或以折线图或堆积面积图的形式显示。每个控制面板最多可以包含 100 个小部件。显示指标的小部件还可以与 CloudWatch 警报相关联。控制面板有 JSON 表示形式，现在您可以在控制台中看到并编辑它。只需单击 Action 菜单并选择 View/edit source 即可：

下面是我的控制面板源：

您可以使用此 JSON 作为您自己的应用程序的起点。如您所见，控制面板中每个小部件的 widgets 数组中都有一个条目；每个条目描述一个小部件，从其类型、位置和大小开始。

使用 API 创建控制面板

假设我要在特定区域为我的每个 EC2 实例创建一个含有小部件的控制面板。我会使用 Python 和适用于 Python 的 AWS 软件开发工具包，然后按如下所示开始创建 (请原谅我的代码不够专业)：

Python

import boto3import json
cw  = boto3.client("cloudwatch")ec2 = boto3.client("ec2")
x, y          = [0, 0]width, height = [3, 3]max_width     = 12widgets       = []

接着，我直接对实例进行迭代，以便为每个实例创建 widget 词典，并将其附加在 widgets 数组中：

Python

instances = ec2.describe_instances()for r in instances['Reservations']:    for i in r['Instances']:
        widget = {'type'      : 'metric',                  'x'         : x,                  'y'         : y,                  'height'    : height,                  'width'     : width,                  'properties': {'view'    : 'timeSeries',                                 'stacked' : False,                                 'metrics' : [['AWS/EC2', 'NetworkIn', 'InstanceId', i['InstanceId']],                                              ['.',       'NetworkOut', '.',         '.']                                             ],                                 'period'  : 300,                                 'stat'    : 'Average',                                 'region'  : 'us-east-1',                                 'title'   : i['InstanceId']                                }                 }
        widgets.append(widget)

我更新循环内的位置 (x 和 y)，并形成一个网格 (如果我不指定位置，则小部件会从左向右、从上至下进行排列)：

Python

x += width        if (x + width > max_width):            x = 0            y += height

处理完所有实例后，我创建一个 JSON 版本的小部件数组：

Python

body   = {'widgets' : widgets}body_j = json.dumps(body)

接下来，我创建或更新我的控制面板：

Python

cw.put_dashboard(DashboardName = "EC2_Networking",                 DashboardBody = body_j)

运行代码后，会获得以下控制面板：

CloudWatch 团队建议，以编程方式创建的控制面板应包括文本小部件 (用于说明控制面板是自动生成的) 以及指向所使用的源代码或 CloudFormation 模板的链接。这样可防止用户在外部对控制面板进行手动更改。如前所述，每个指标小部件还可以与一个 CloudWatch 警报相关联。您可以通过编程方式或使用 CloudFormation 模板来创建警报，如示例 CPU 使用率警报。如果您决定这样做，则警报阈值会显示在小部件中。要详细了解此操作，请阅读 Tara Walker 近期发布的文章 Amazon CloudWatch 发布了控制面板警报功能。更进一步的操作是，我可以使用 CloudWatch Events 和 Lamba 函数来跟踪某些资源的创建与删除，并在发生更改时更新控制面板。要了解如何执行此类操作，请阅读使用 AWS Lambda 让 CloudWatch 控制面板保持最新。

使用 CLI 访问控制面板 我还可以通过命令行访问和操作我的控制面板。例如，我可以生成一个简单的列表：

Bash

$ aws cloudwatch list-dashboards --output table----------------------------------------------|               ListDashboards               |+--------------------------------------------+||             DashboardEntries             |||+-----------------+----------------+-------+|||  DashboardName  | LastModified   | Size  |||+-----------------+----------------+-------+|||  Disk-Metrics   |  1496405221.0  |  316  ||||  EC2_Networking |  1498090434.0  |  2830 ||||  Main-Metrics   |  1498085173.0  |  234  |||+-----------------+----------------+-------+|

然后，我删除 Disk-Metrics 控制面板：

Bash

$ aws cloudwatch delete-dashboards --dashboard-names Disk-Metrics

此外，也可以检索用于定义控制面板的 JSON：

使用 CloudFormation 创建控制面板

控制面板还可以在 CloudFormation 模板中进行指定。下面是一个简单的 YAML 格式的模板 ( DashboardBody 仍以 JSON 指定)：

YAML

Resources:  MyDashboard:    Type: "AWS::CloudWatch::Dashboard"    Properties:      DashboardName: SampleDashboard      DashboardBody: '{"widgets":[{"type":"text","x":0,"y":0,"width":6,"height":6,"properties":{"markdown":"Hi there from CloudFormation"}}]}'

我将模板放置在一个文件中，然后使用控制台或 CLI 创建堆栈：

Bash

$ aws cloudformation create-stack --stack-name MyDashboard --template-body file://dash.yaml{    "StackId": "arn:aws:cloudformation:us-east-1:xxxxxxxxxxxx:stack/MyDashboard/a2a3fb20-5708-11e7-8ffd-500c21311262"}

下面是控制面板：

现已推出

此功能现已推出，您可以立即开始使用。您可以免费创建 3 个控制面板，每个控制面板最多包含 50 项指标；如果创建的控制面板超过 3 个，则每月需支付 3 USD (相关价格信息，请访问 CloudWatch 定价页面)。您每月最多可以免费调用 100 万次新 API 函数；如果超出此范围，则每调用 1000 次需支付 0.01 USD。

本文转载自 AWS 技术博客。

原文链接：

https://amazonaws-china.com/cn/blogs/china/new-api-cloudformation-support-for-amazon-cloudwatch-dashboards/