# Amazon Athena CloudWatch 指标连接器
<a name="connectors-cwmetrics"></a>

借助 Amazon Athena CloudWatch 指标连接器，Amazon Athena 可以使用 SQL 查询 CloudWatch 指标数据。

此连接器不使用 Glue 连接将配置属性集中保存到 Glue 中。连接配置通过 Lambda 完成。

有关从 Athena 本身向 CloudWatch 发布查询指标的信息，请参阅 [使用 CloudWatch 和 EventBridge 监控查询并控制成本](workgroups-control-limits.md)。

## 先决条件
<a name="connectors-cwmetrics-prerequisites"></a>
+ 可以使用 Athena 控制台或 AWS Serverless Application Repository 将该连接器部署到您的 AWS 账户。有关更多信息，请参阅 [创建数据来源连接](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署数据来源连接器](connect-data-source-serverless-app-repo.md)。

## 参数
<a name="connectors-cwmetrics-parameters"></a>

使用本节中的参数来配置 CloudWatch 指标连接器。

### Glue 连接（推荐）
<a name="connectors-cwmetrics-gc"></a>

我们建议您使用 Glue 连接对象来配置 CloudWatch Metrics 连接器。要执行此操作，请将 CloudWatch Metrics 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。

**Glue 连接属性**

使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。

```
aws glue describe-connection-type --connection-type CLOUDWATCHMETRICS
```

**Lambda 环境属性**
+ **glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。

**注意**  
所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。
使用 Glue 连接创建的 CloudWatch Metrics 连接器不支持使用多路复用处理程序。
使用 Glue 连接创建的 CloudWatch Metrics 连接器仅支持 `ConnectionSchemaVersion` 2。

### 旧连接
<a name="connectors-cwmetrics-legacy"></a>
+ **spill\$1bucket** - 为超出 Lambda 函数限制的数据指定 Amazon S3 存储桶。
+ **spill\$1prefix** -（可选）默认为指定 `spill_bucket`（称为 `athena-federation-spill`）中的子文件夹。我们建议您在此位置配置 Amazon S3 [存储生命周期](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)，以删除早于预定天数或小时数的溢出内容。
+ **spill\$1put\$1request\$1headers** —（可选）用于溢出的 Amazon S3 `putObject` 请求的请求标头和值的 JSON 编码映射（例如 `{"x-amz-server-side-encryption" : "AES256"}`)。有关其他可能的标头，请参阅《[Amazon Simple Storage Service API 参考](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)》中的 *PutObject*。
+ **kms\$1key\$1id** -（可选）默认情况下，将使用经过 AES-GCM 身份验证的加密模式和随机生成的密钥对溢出到 Amazon S3 的任何数据进行加密。要让您的 Lambda 函数使用 KMS 生成的更强的加密密钥（如 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`），您可以指定 KMS 密钥 ID。
+ **disable\$1spill\$1encryption** -（可选）当设置为 `True` 时，将禁用溢出加密。默认值为 `False`，此时将使用 AES-GCM 对溢出到 S3 的数据使用进行加密 - 使用随机生成的密钥，或者使用 KMS 生成密钥。禁用溢出加密可以提高性能，尤其是当您的溢出位置使用[服务器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)时。

该连接器还支持 [AIMD 拥塞控制](https://en.wikipedia.org/wiki/Additive_increase/multiplicative_decrease)，以通过 [Amazon Athena Query Federation SDK](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-federation-sdk) `ThrottlingInvoker`构造处理来自 CloudWatch 的节流事件。您可以通过设置以下任何可选环境变量来调整默认的节流行为：
+ **throttle\$1initial\$1delay\$1ms** - 在第一个拥塞事件之后应用的初始调用延迟。默认为 10 毫秒。
+ **throttle\$1max\$1delay\$1ms** - 调用之间的最大延迟时间。您可以通过将其分成 1000 毫秒来推导 TPS。默认为 1000 毫秒。
+ **throttle\$1decrease\$1factor** – Athena 降低调用速率的因子。默认值为 0.5。
+ **throttle\$1increase\$1ms** – Athena 减少调用延迟的速率。默认为 10 毫秒。

## 数据库和表
<a name="connectors-cwmetrics-databases-and-tables"></a>

Athena CloudWatch 指标连接器将您的命名空间、维度、指标和指标值映射到名为 `default` 的单个架构中的两个表中。

### 指标表
<a name="connectors-cwmetrics-the-metrics-table"></a>

`metrics` 表包含由命名空间、集合和名称的组合唯一定义的可用指标。`metrics` 表包含以下列。
+ **命名空间** - 包含命名空间的 `VARCHAR`。
+ **metric\$1name** - 包含指标名称的 `VARCHAR`。
+ **维度** - `LIST``STRUCT` 对象，由 `dim_name (VARCHAR)` 和 `dim_value (VARCHAR)` 组成。
+ **统计数据** - 可用于该指标的 `LIST``VARCH` 统计数据（例如，`p90`、`AVERAGE`...）。

### metric\$1samples 表
<a name="connectors-cwmetrics-the-metric_samples-table"></a>

`metric_samples` 表包含 `metrics` 表中每个指标的可用指标示例。`metric_samples` 表包含以下列。
+ **命名空间** - 包含命名空间的 `VARCHAR`。
+ **metric\$1name** - 包含指标名称的 `VARCHAR`。
+ **维度** - `STRUCT` 对象的 `LIST`，由 `dim_name (VARCHAR)` 和 `dim_value (VARCHAR)` 组成。
+ **dim\$1name** - 可用于轻松筛选单个维度名称的 `VARCHAR` 便捷字段。
+ **dim\$1value** - 可用于轻松筛选单个维度值的 `VARCHAR` 便捷字段。
+ **周期** - 表示指标“周期”的 `INT` 字段，以秒为单位（例如，60 秒指标）。
+ **时间戳** - 表示指标样本纪元时间的 `BIGINT` 字段（以秒为单位）。
+ **值** - 包含样本值的 `FLOAT8` 字段。
+ **统计数据** - 包含样本统计类型的 `VARCHAR`（例如，`AVERAGE` 或 `p90`)。

## 所需权限
<a name="connectors-cwmetrics-required-permissions"></a>

要获取有关此连接器所需 IAM policy 的完整详细信息，请查看 [athena-cloudwatch-metrics.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudwatch-metrics/athena-cloudwatch-metrics.yaml) 文件的 `Policies` 部分。以下列表汇总了所需的权限。
+ **Amazon S3 写入权限** – 连接器需要对 Amazon S3 中的位置具有写入权限，以溢出大型查询的结果。
+ **Athena GetQueryExecution** – 当上游 Athena 查询终止时，该连接器将使用此权限快速失败。
+ **CloudWatch 指标只读** - 连接器使用此权限来查询您的指标数据。
+ **CloudWatch 日志写入** - 连接器使用此权限写入其诊断日志。

## 性能
<a name="connectors-cwmetrics-performance"></a>

Athena CloudWatch 指标连接器尝试通过并行扫描查询所需的日志流来优化针对 CloudWatch 指标的查询。在特定时间段、指标、命名空间和维度筛选条件下，谓词下推既在 Lambda 函数内执行，也在 CloudWatch 日志中执行。

## 许可证信息
<a name="connectors-cwmetrics-license-information"></a>

Amazon Athena CloudWatch 指标连接器项目已根据 [Apache-2.0 许可证](https://www.apache.org/licenses/LICENSE-2.0.html)获得许可。

## 其他资源
<a name="connectors-cwmetrics-additional-resources"></a>

有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudwatch-metrics)。