小组件参考

关于本页

本页供查阅之用：每种 CloudWatch 小组件在各种尺寸下如何绘制，以及 CloudPeek 具体使用控制面板 JSON 的哪些部分。预设和 AI 小组件采用相同的 JSON 编写，因此本页内容同样适用于它们。要制作小组件，请参阅创建小组件。

创建小组件的内容现已移至单独的页面：创建小组件。

预设现已移至单独的页面：预设。

AI 小组件现已移至单独的页面：AI 小组件。

“小组件”标签页的内容现已移至主屏幕和锁定屏幕。

刷新和数据新旧程度的内容现已移至 CloudPeek 的工作原理。

小组件类型

每种 CloudWatch 指标小组件视图，以及文本和警报状态小组件，都会成为 iPhone、iPad 和 Android 上的原生小组件，并按控制面板的颜色、阈值和坐标轴范围绘制。

列表显示不下时

• 条形：如果将剩余条形相加有意义（货币，或同一指标的计数和总和），最后一个条形会变成灰色的其他条形，显示它们的总计。否则会显示“还有 N 项”。显示的条形是离零最远的那些；如果小组件的阈值为低于，则显示最低的那些（请参阅警告阈值和警报阈值）。
• 总计：如果控制面板中有总计（例如账户级的 EstimatedCharges 行或 SUM(METRICS()) 表达式），条形图或饼图小组件就会显示总计。该行不会单独绘制为一个条形。包含多个条形的货币小组件会自行计算它们的总计。
• 饼图：会绘制每个扇区；图例会尽可能多地列出扇区，然后显示“还有 N 项”。如果总计大于各扇区之和，差额会显示为灰色的其他扇区。
• 折线图和堆叠面积图上的图例在中号小组件上最多列出四个数据系列（文字较大时更少），在大号小组件上列出四个，每个系列都附有最新值，然后显示“还有 N 项”。小号小组件没有图例。
• 表格和警报列表会尽可能多地显示行，然后显示“还有 N 项”。每个周期一行的表格会显示最新的行，然后显示“更早 N 项”。

尺寸

每个小组件都提供所有尺寸。CloudPeek 会在你添加之前预览每种尺寸。在 Android 上，你可以通过调整主屏幕小组件的大小来选择尺寸，它会根据可用空间显示相应的布局：110 × 110 dp 起为小号，250 × 110 dp 起为中号，250 × 250 dp 起为大号。在一排可放四个应用的主屏幕上，分别为 2 × 2、4 × 2 和 4 × 4 格。

• 小号小组件没有图例和页脚。警报小组件以摘要开头，例如“1 个警报中”。
• 中号及更大的小组件会增加刷新按钮、图例，以及显示时间范围和更新时间的页脚，例如“过去 3 小时 · 更新于 14:05”。警报列表会显示每个警报多久前发生了变化。
• 大号小组件会增加更多坐标轴标签。iPad 上的特大号是空间更宽敞的大号布局；在 Android 上，每种布局都会绘制为填满你给它的空间。
• 带有总计的条形图小组件在小号和中号尺寸上会让出一个位置给总计。
• 能显示的行数取决于你的文字大小；其余的会计为“还有 N 项”。
• 在 iPhone 上，待机显示会以更大的尺寸在黑色背景上显示小号小组件；Mac 桌面可以显示 iPhone 的小号、中号和大号小组件（请参阅待机显示和在 Mac 上）。

警报列表

警报小组件按以下顺序列出警报，每个警报都附有其状态：

• 在每种状态内，警报保持小组件列出它们的顺序；如果设置了 "sortBy": "stateUpdatedTimestamp"，则最近发生变化的排在最前。
• 中号及更大的小组件会显示每个警报的状态在多久前发生了变化。
• 小号小组件和锁定屏幕上的摘要：有任何警报处于警报状态时，以红色显示 N 个警报中；所有警报都正常时，以绿色显示全部正常；所有警报都还没有足够数据时，显示无数据；否则显示 N 个未知，统计没有数据或找不到的警报。
• 警报摘要预设则会统计每种状态的警报数量，例如“2 个异常、4 个数据不足、14 个正常”：请参阅预设。
• 涵盖所有账户的警报预设会为每个账户显示一行，最严重的排在最前，并带有其最严重状态的符号，例如“prod：2 个异常”；警报还会在该行下方列出该账户中不正常的警报。请参阅所有账户中的警报。

锁定屏幕

iPhone 和 iPad 上的锁定屏幕小组件只显示一个主要值，让你无需解锁即可查看。Android 手机没有锁定屏幕小组件。

• 矩形：标题、值以及该值所属的数据系列或条形（如果数据不是最新的，则显示警告）。
• 圆形：值以及取自标题、约 8 个字符的说明文字。
• 内联（位于时钟上方）：值和标题，标题按完整单词截断为约 18 个字符。
• 阈值：超过小组件警告阈值或警报阈值的值旁边会显示该阈值的符号，因为锁定屏幕只用一种颜色绘制（请参阅警告阈值和警报阈值）。

概览小组件

概览小组件以最新值的形式显示你的两到四个小组件（请参阅在一个小组件中显示多个值）：小号显示两个，中号及更大的显示四个；在 iPhone 和 iPad 上，锁定屏幕显示第一个。

• 值是每个小组件在锁定屏幕上的主要值，见上表。警报小组件（包括“警报摘要”预设）会显示其摘要，例如带红色三角形的红色“1 个警报中”、带绿色对勾的绿色“全部正常”，或在没有警报时显示“无警报”。涵盖所有账户的警报小组件则会显示最严重的、需要查看的账户所在的行，例如“prod：2 个异常”或“dev：登录以刷新”，这样无法读取的账户就不会被其他账户的“全部正常”掩盖。
• 阈值：超过其小组件警告阈值的值显示为琥珀色并带有圆圈“!”，超过警报阈值的值显示为红色并带有三角形，与小组件本身相同（请参阅警告阈值和警报阈值）。与阈值比较的是所显示的值；条形的总计本身不与阈值比较，而是采用其中任一条形所超过的最严重阈值。
• 趋势以箭头和百分比（例如“+12%”）表示该值相对于前一个数据点的变化：适用于显示趋势的数字小组件、仪表，以及折线图或堆叠面积图。条形图、饼图、表格、警报以及绘制为柱的图表没有趋势：一根柱通常代表一个仍在进行中的周期，例如今天截至目前的支出。
• 文本小组件没有值，因此概览小组件不提供它们。
• 无法刷新的小组件会保留最后的值，并在趋势的位置用橙色说明原因：“登录以刷新”、“账户未添加”或“自14:05起未更新”；如果没有可保留的值，则显示“访问被拒绝”、“无法连接 AWS”等。超过一天的数据会变淡显示。

CloudPeek 使用的控制面板设置

CloudPeek 会读取控制面板的 JSON，并以与 CloudWatch 控制台相同的方式进行查询。预设和 AI 小组件采用相同的 JSON 编写，因此以下所有内容同样适用于它们。

支持

• 指标：使用 "." 和 "..." 简写的指标行；指标数学、SEARCH 和 Metrics Insights（SELECT … FROM SCHEMA(…)）表达式；用于不应绘制的输入的 "visible": false。
• 每个指标：id、label（包括 ${PROP('Dim.ServiceName')} 和 ${LAST} 等动态标签）、color、stat、period、region、accountId 和 yAxis。
• 每个小组件：title、view、stacked、stat（未设置时为 Average）、period、region、accountId、start、end、setPeriodToTimeRange、sparkline、trend、任一侧 Y 轴的 min 和 max、水平 annotations（值、颜色、坐标轴和 visible），以及 "legend": {"position": "hidden"}。
• 右侧 Y 轴：设置了 "yAxis": "right" 的指标会使用单独的刻度绘制，刻度标签显示在右侧。
• 每个控制面板：start、end 和 periodOverride。
• 警报小组件：alarms 和 sortBy。

不使用

• 注释标签和 Y 轴标签（会绘制线条和范围，但不显示其文字）、注释带（只绘制其第一条边）以及垂直注释。
• 除隐藏以外的图例位置、liveData、singleValueFullPrecision 以及表格摘要选项。
• 控制面板变量：小组件使用控制面板中保存的值。

时间范围和周期

• 时间范围：如果小组件有 start，则使用它；否则使用控制面板的设置；再否则使用过去 3 小时。-PT3H 或 -P7D 这类相对范围和绝对时间戳都可以使用。每个小组件都会显示其涵盖的时间段，例如“过去 3 小时”。
• 周期：使用指标的 period；否则使用小组件的设置；再否则使用 5 分钟。与控制台一样，当时间范围需要的数据点过多时（超过 300 个，或在设置了 "periodOverride": "inherit" 时超过 1,440 个），CloudPeek 会增大周期，依次为 1 分钟、5 分钟、15 分钟、1 小时、3 小时、6 小时、1 天、1 周和 30 天。
• 较早的数据在 CloudWatch 中的分辨率较粗，因此起点早于 15 天前的时间范围至少使用 5 分钟周期，起点早于 63 天前的至少使用 1 小时周期。
• setPeriodToTimeRange 会让数字、仪表、条形图、饼图和表格小组件对整个时间范围使用一个周期，与控制台相同。

值的显示方式

• 数字保留三位有效数字，并用 K、M、B 和 T 分别表示千、百万、十亿和万亿：1.23K、45.6M。如果保留三位会四舍五入成一个容易误导的整数，则会保留更多位数，因此 99.96 不会显示为 100。CloudWatch 的单位不会显示，因此请将单位写在标签中，例如“延迟（秒）”。
• 货币：当小组件上的每个指标都是同一货币的 AWS/Billing EstimatedCharges 时，值会以金额形式显示：低于 100 时显示到分，10,000 以内显示整数金额，再往上则使用紧凑格式，例如 $12.3K。未指定 Currency 的 AWS/Billing 的 SEARCH 会以美元显示，这是 AWS 发布费用所用的唯一货币。
• 账单小组件上的服务名称会被缩短：AmazonEC2 变为 EC2，AWSLambda 变为 Lambda。
• 标签：没有标签的指标会以指标名称命名，或以能将它与小组件上其他指标区分开的维度值命名。
• 数字上的趋势会将最新数据点与前一个数据点进行比较。
• 颜色：使用你为每个指标设置的 color，否则使用 CloudWatch 的默认调色板。
• 警告阈值和警报阈值：数字、仪表、条形或图表的最新值超过你在 CloudPeek 中设置的阈值时，会显示为琥珀色或红色，并带有符号（请参阅警告阈值和警报阈值）。CloudPeek 会将其阈值作为标记了 "cloudPeekLevel" 的水平注释写入小组件，图表会将其绘制为虚线。控制面板自己的注释也会绘制为线条，但永远不会为值着色。

账户、区域和限制

• 区域：每个指标依次使用其自己的 region、小组件的区域，以及账户在 CloudPeek 中的默认区域。一个小组件可以混合多个区域；CloudPeek 会并行查询每个区域。
• 账户：每个小组件都使用其所属的账户刷新。要在一个小组件上显示其他账户的指标，请配合 CloudWatch 跨账户可观测性在指标上使用 accountId，或者将那个账户添加到 CloudPeek 并为它创建小组件。
• 警报会在小组件所属的账户中、在每个 ARN 指定的区域中查找。警报预设最多读取其添加时所在区域中的 1,000 个警报（如果在显示下选择了文本，则只读取名称以该文本开头的警报）；超过这个数量时，保留的是处于 ALARM 状态的警报。
• 大小：一个小组件每次在每个区域最多可请求 500 个指标，每条线最多保留 400 个数据点。图表最多绘制 30 个数据系列：折线图显示值最高的 30 个，堆叠图则将其余的合计为“其他”。

文本小组件

文本小组件很适合在图表旁放一条运行手册备注。CloudPeek 会显示：

• 粗体、斜体、code 和链接。
• 标题，显示为粗体行。
• 项目符号列表（*、- 或 +），显示为项目符号。
• CloudWatch 的按钮 [button:Label](https://…)，显示为普通链接。

水平线会被省略，连续的空行会被合并。表格、图片和代码块最好只放在控制台中的控制面板上。没有标题的文本小组件会以其第一行命名。