创建自定义数据来源连接器。 - Amazon CloudWatch
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

创建自定义数据来源连接器。

要将自定义数据来源连接到 CloudWatch,可使用两种选项:

  • 首先使用 CloudWatch 提供的示例模板。您可以通过该模板使用 JavaScript 或 Python。这些模板包含示例 Lambda 代码,这些代码将有助于您创建 Lambda 函数。然后,您可以修改模板中的 Lambda 函数,以便连接到自定义数据来源。

  • 从头开始创建 Amazon Lambda 函数,用于实现数据来源连接器、数据查询以及准备供 CloudWatch 使用的时间序列。此函数必须按需预聚合或合并数据点,还必须调整周期和时间戳以与 CloudWatch 兼容。

使用模板

使用模板可以创建示例 Lambda 函数,帮助您更快地构建自定义连接器。这些示例函数为构建自定义连接器所涉及的许多常见场景提供了示例代码。使用模板创建连接器后,您可以检查 Lambda 代码,然后对其进行修改以用于连接数据来源。

此外,如果使用该模板,CloudWatch 会负责创建 Lambda 权限策略并将资源标签附加到 Lambda 函数。

使用模板创建连接到自定义数据来源的连接器
  1. 访问 https://console.aws.amazon.com/cloudwatch/ 打开 CloudWatch 控制台。

  2. 在导航窗格中,选择设置

  3. 选择指标数据来源选项卡。

  4. 选择创建数据源

  5. 选择自定义:入门模板单选按钮,然后选择下一步

  6. 输入数据源的名称。

  7. 从列出的模板中选择一个。

  8. 选择 Node.js 或 Python。

  9. 选择创建数据源

    Amazon CloudFormation 堆栈完成创建自定义来源之后,您刚刚添加的新自定义来源才会出现。要查看进度,可以选择查看我的 CloudFormation 堆栈的状态。您也可以通过刷新图标来更新此列表。

    新数据来源出现在此列表中时,即可在控制台中进行测试和修改。

  10. (可选)要在控制台中查询来自该来源的测试数据,请按照 创建源自另一个数据来源的指标图表 中的说明操作。

  11. 按需修改 Lambda 函数。

    1. 在导航窗格中,选择设置

    2. 选择指标数据来源选项卡。

    3. 为要修改的来源选择在 Lambda 控制台中查看

    您现在可以修改函数以访问数据来源。有关更多信息,请参阅 步骤 1:创建函数

    注意

    通过使用该模板,在编写 Lambda 函数时,无需按照 步骤 2:创建 Lambda 权限策略 步骤 3:将资源标签附加到 Lambda 函数 中的说明进行操作。由于您使用了该模板,因此 CloudWatch 会执行这些步骤。

从头开始创建自定义数据来源

按照本节中的步骤创建 Lambda 函数,将 CloudWatch 连接到数据来源。

步骤 1:创建函数

自定义数据来源连接器必须支持来自 CloudWatch 的 GetMetricData 事件。您也可以实施 DescribeGetMetricData 活动,以便在 CloudWatch 控制台中向用户提供有关如何使用连接器的文档。该 DescribeGetMetricData 响应还可用于设置 CloudWatch 自定义查询构建器中使用的默认值。

CloudWatch 提供了代码段示例,以帮助您入门。有关更多信息,请参阅 https://github.com/aws-samples/cloudwatch-data-source-samples 上的示例存储库。

约束

  • 来自 Lambda 的响应必须小于 6 Mb。如果响应超过 6 Mb,则 GetMetricData 响应会将 Lambda 函数标记为 InternalError,并且不会返回任何数据。

  • 如果用于可视化和控制面板管理,Lambda 函数必须在 10 秒内完成执行;如果用于警报,则必须在 4.5 秒内完成执行。如果执行超时,则 GetMetricData 响应会将 Lambda 函数标记为 InternalError,并且不会返回任何数据。

  • Lambda 函数必须使用以秒为单位的纪元时间戳发送其输出。

  • 如果 Lambda 函数不对数据进行重采样,而是返回与 CloudWatch 用户请求的开始时间和时段长度不一致的数据,则 CloudWatch 将忽略该数据。多余的数据将从任何可视化或警报中丢弃。任何未介于开始时间和结束时间之间的数据也会被丢弃。

    例如,如果用户要求提供 10:00 到 11:00 之间的数据,周期为 5 分钟,则“10:00:00 至 10:04:59”和“10:05:00 至 10:09:59”为返回数据的有效时间范围。您必须返回包含 10:00 value110:05 value2 等的时间序列。例如,如果函数返回 10:03 valueX,则会被丢弃,因为 10:03 与请求的开始时间和周期不对应。

  • CloudWatch 数据来源连接器不支持多行查询。执行查询,或者使用查询创建警报或控制面板小组件时,每个换行符都会替换为空格。在某些情况下,这可能会导致查询无效。

GetMetricData 事件

请求负载

以下是作为输入发送到 Lambda 函数的 GetMetricData 请求负载示例。

{ "EventType": "GetMetricData", "GetMetricDataRequest": { "StartTime": 1697060700, "EndTime": 1697061600, "Period": 300, "Arguments": ["serviceregistry_external_http_requests{host_cluster!=\"prod\"}"] } }
  • StartTime:指定返回的最早数据的时间戳。类型为时间戳纪元秒。

  • EndTime:指定返回的最新数据的时间戳。类型为时间戳纪元秒。

  • Period:每个指标数据聚合所代表的秒数。最短时间为 60 秒。类型为秒。

  • Arguments:要传递给 Lambda 指标数学表达式的参数数组。有关传递参数的更多信息,请参阅 如何将参数传递给您的 Lambda 函数

响应负载

以下是 Lambda 函数返回的 GetMetricData 响应负载的示例。

{ "MetricDataResults": [ { "StatusCode": "Complete", "Label": "CPUUtilization", "Timestamps": [ 1697060700, 1697061000, 1697061300 ], "Values": [ 15000, 14000, 16000 ] } ] }

该响应负载将包含 MetricDataResults 字段或 Error 字段,但无法二者皆包含。

MetricDataResults 字段是 MetricDataResult 类型的时间序列字段列表。每个时间序列字段可包括以下字段。

  • StatusCode –(可选)Complete 表示已返回请求时间范围内的所有数据点。PartialData 表示返回的数据点不完整。如果省略,则使用默认值 Complete

    有效值: Complete | InternalError | PartialData | Forbidden

  • Messages:可选的消息列表,其中包含有关返回的数据的其他信息。

    类型:包含 CodeValue 字符串的 MessageData 对象数组。

  • Label:与数据关联的便于阅读的标签。

    类型:字符串

  • Timestamps:数据点的时间戳,格式为纪元时间。时间戳的数量始终与值的数量相匹配,Timestamps[x] 的值为 Values[x]。

    类型:时间戳数组

  • Values:与 Timestamps 对应的指标数据点值。值的数量始终与时间戳的数量相匹配,Timestamps[x] 的值为 Values[x]。

    类型:双倍数组

有关 Error 对象的更多信息,请参阅以下部分。

错误响应格式

您可以选择使用错误响应来提供有关错误的更多信息。当发生验证错误时(例如缺少参数或参数类型错误),我们建议您使用代码验证返回错误。

以下是 Lambda 函数要引发 GetMetricData 验证异常时的响应示例。

{ "Error": { "Code": "Validation", "Value": "Invalid Prometheus cluster" } }

以下是 Lambda 函数表示由于访问问题而无法返回数据时的响应示例。响应被转换为状态代码为 Forbidden 的单个时间序列。

{ "Error": { "Code": "Forbidden", "Value": "Unable to access ..." } }

以下是 Lambda 函数引发整体 InternalError 异常的示例,该异常被转换为拥有状态代码 InternalError 和一条消息的单个时间序列。只要错误代码的值不是 ValidationForbidden,CloudWatch 都会认为这属于通用内部错误。

{ "Error": { "Code": "PrometheusClusterUnreachable", "Value": "Unable to communicate with the cluster" } }

DescribeGetMetricData 事件

请求负载

以下是一个 DescribeGetMetricData 请求负载的示例。

{ "EventType": "DescribeGetMetricData" }

响应负载

以下是 DescribeGetMetricData 响应负载的示例。

{ "Description": "Data source connector", "ArgumentDefaults": [{ Value: "default value" }] }
  • Description:关于如何使用数据来源连接器的描述。此描述将显示在 CloudWatch 控制台中。支持 Markdown。

    类型:字符串

  • ArgumentDefaults:预填充自定义数据来源构建器时使用的参数默认值的可选数组。

    如果返回 [{ Value: "default value 1"}, { Value: 10}],则 CloudWatch 控制台中的查询构建器会显示两个输入,第一个输入拥有“默认值 1”,第二个输入拥有“默认值 10”。

    如果未提供 ArgumentDefaults,则显示默认类型为 String 的单个输入。

    类型:包含值和类型的对象数组。

  • Error –(可选)错误字段可包含在任何响应中。您可以在 GetMetricData 事件 中查看示例。

CloudWatch 警报的重要注意事项

如果要使用数据来源设置 CloudWatch 警报,则应将其设置为每分钟向 CloudWatch 报告带有时间戳的数据。有关对已连接的数据来源的指标创建警报的更多信息和其他注意事项,请参阅 基于连接的数据来源创建警报

(可选)使用 Amazon Secrets Manager 存储凭证

如果您的 Lambda 函数需要使用凭证来访问数据来源,我们建议使用 Amazon Secrets Manager 来存储这些凭证,而不是将其硬编码到您的 Lambda 函数中。有关结合使用 Amazon Secrets Manager 和 Lambda 函数的更多信息,请参阅在 Amazon Lambda 函数中使用 Amazon Secrets Manager 密钥

(可选)连接到 VPC 中的数据来源

如果数据来源位于由 Amazon Virtual Private Cloud 管理的 VPC 中,则必须配置您的 Lambda 函数才能对其进行访问。有关更多信息,请参阅将出站联网连接到 VPC 中的资源

您可能还需要配置 VPC 服务端点才能访问 Amazon Secrets Manager 等服务。有关更多信息,请参阅使用接口 VPC 端点访问 Amazon 服务

步骤 2:创建 Lambda 权限策略

您必须创建策略语句,授予 CloudWatch 使用您创建的 Lambda 函数的权限。您可以使用 Amazon CLI 或 Lambda 控制台创建该策略语句。

使用 Amazon CLI 创建策略语句
  • 输入以下 命令。将 123456789012 替换为您的账户 ID,将 my-data-source-function 替换为您的 Lambda 函数的名称,然后将 MyDataSource-DataSourcePermission1234 替换为任意唯一值。

    aws lambda add-permission --function-name my-data-source-function --statement-id MyDataSource-DataSourcePermission1234 --action lambda:InvokeFunction --principal lambda.datasource.cloudwatch.amazonaws.com --source-account 123456789012

步骤 3:将资源标签附加到 Lambda 函数

CloudWatch 控制台通过使用标签来确定哪些 Lambda 函数是数据来源连接器。使用其中一个向导创建数据来源时,配置该标签的 Amazon CloudFormation 堆栈会自动应用该标签。当您自己创建数据来源时,可以将以下标签用于 Lambda 函数。这样一来,当您查询指标时,您的连接器就会显示在 CloudWatch 控制台的数据来源下拉列表中。

  • 具有键 cloudwatch:datasource 和值 custom 的标签。