本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# Amazon Athena CloudWatch 連接器
<a name="connectors-cloudwatch"></a>

Amazon Athena CloudWatch 連接器讓 Amazon Athena 能夠與 CloudWatch 通訊，以便使用 SQL 來查詢您的日誌資料。

此連接器不會使用 Glue 連線來集中 Glue 中的組態屬性。連線組態是透過 Lambda 完成的。

此連接器將 LogGroups 映射為結構描述，將每個 LogStream 映射為資料表。此連接器也映射特殊的 `all_log_streams` 檢視，其中包含 LogGroup 中的所有 LogStream。此檢視可讓您一次查詢 LogGroup 中的所有日誌，而不是個別搜尋每個 LogStream。

## 先決條件
<a name="connectors-cloudwatch-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) 。

## Parameters
<a name="connectors-cloudwatch-parameters"></a>

使用本節中的參數來設定 CloudWatch 連接器。

### Glue 連線 (建議)
<a name="connectors-cloudwatch-gc"></a>

我們建議您使用 Glue 連線物件來設定 CloudWatch 連接器。為此，請將 CloudWatch 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。

**Glue 連線屬性**

使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。

```
aws glue describe-connection-type --connection-type CLOUDWATCH
```

**Lambda 環境屬性**
+ **glue\$1connection** – 指定與聯合連接器關聯的 Glue 連線名稱。

**注意**  
使用 Glue 連線的所有連接器都必須使用 AWS Secrets Manager 來存放登入資料。
使用 Glue 連線建立的 CloudWatch 連接器不支援使用多工處理常式。
使用 Glue 連線建立的 CloudWatch 連接器僅支援 `ConnectionSchemaVersion` 2。

### 舊版連線
<a name="connectors-cloudwatch-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 參考**》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。
+ **kms\$1key\$1id** - (選用) 依預設，任何溢出到 Amazon S3 的資料都會使用 AES-GCM 驗證加密模式和隨機產生的金鑰進行加密。為了讓您的 Lambda 函數使用 KMS 產生的更強大的加密金鑰，例如 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`，您可以指定 KMS 金鑰 ID。
+ **disable\$1spill\$1encryption** - (選用) 當設定為 `True` 時，停用溢出加密。預設為 `False`，因此溢出 S3 的資料會使用 AES-GCM 進行加密 — 使用隨機產生的金鑰或 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 軟體開發套件](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-cloudwatch-databases-and-tables"></a>

Athena CloudWatch 連接器將 LogGroups 映射為結構描述 (即資料庫)，將每個 LogStream 映射為資料表。此連接器也映射特殊的 `all_log_streams` 檢視，其中包含 LogGroup 中的所有 LogStream。此檢視可讓您一次查詢 LogGroup 中的所有日誌，而不是個別搜尋每個 LogStream。

Athena CloudWatch 連接器映射的每個資料表都具有下列結構描述。此結構描述符合 CloudWatch Logs 提供的欄位。
+ **log\$1stream** - 一個 `VARCHAR`，它包含資料列所在之 LogStream 的名稱。
+ **time** - 一個 `INT64`，它包含產生日誌行時的 epoch 時間。
+ **message** - 包含日誌消息的 `VARCHAR`。

**範例**  
下列範例會示範如何對指定的 LogStream 執行 `SELECT` 查詢。

```
SELECT * 
FROM "lambda:cloudwatch_connector_lambda_name"."log_group_path"."log_stream_name" 
LIMIT 100
```

下列範例會示範如何使用 `all_log_streams` 檢視，在指定的 LogGroup 中對所有 LogStream 執行查詢。

```
SELECT * 
FROM "lambda:cloudwatch_connector_lambda_name"."log_group_path"."all_log_streams" 
LIMIT 100
```

## 所需的許可
<a name="connectors-cloudwatch-required-permissions"></a>

如需詳細了解此連接器所需的 IAM 政策，請檢閱 [athena-cloudwatch.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudwatch/athena-cloudwatch.yaml) 檔案的 `Policies` 部分。以下清單摘要說明所需的許可。
+ **Amazon S3 寫入存取** - 連接器需要 Amazon S3 中某個位置的寫入存取權，以便從大型查詢中溢寫結果。
+ **Athena GetQueryExecution** - 當上游 Athena 查詢終止時，連接器會使用此權限快速失敗。
+ **CloudWatch Logs Read/Write** - 連接器會使用此權限來讀取日誌資料並寫入其診斷日誌。

## 效能
<a name="connectors-cloudwatch-performance"></a>

Athena CloudWatch 連接器透過並行掃描査詢所需的日誌串流，嘗試依據 CloudWatch 來最佳化查詢。對於特定時段篩選條件，會在 Lambda 函數和 CloudWatch Logs 中執行述詞下推。

為了獲得最佳效能，請僅使用小寫作為日誌群組名稱和日誌串流名稱。使用混合大小寫會導致連接器執行運算密集程度較高的不區分大小寫搜尋。

**注意**  
 CloudWatch 連接器不支援大寫資料庫名稱。

## 傳遞查詢
<a name="connectors-cloudwatch-passthrough-queries"></a>

CloudWatch 連接器支援使用 [CloudWatch Logs Insights 查詢語法](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)的[傳遞查詢](federated-query-passthrough.md)。如需有關 CloudWatch Logs Insights 的詳細資訊，請參閱《Amazon CloudWatch Logs 使用者指南**》中的[使用 CloudWatch Logs Insights 分析日誌資料](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html)。

若要透過 CloudWatch 建立傳遞查詢，請使用下列語法：

```
SELECT * FROM TABLE(
        system.query(
            STARTTIME => 'start_time',
            ENDTIME => 'end_time',
            QUERYSTRING => 'query_string',
            LOGGROUPNAMES => 'log_group-names',
            LIMIT => 'max_number_of_results'
        ))
```

下列範例 CloudWatch 傳遞查詢會在 `duration` 欄位不等於 1000 時進行篩選。

```
SELECT * FROM TABLE(
        system.query(
            STARTTIME => '1710918615308',
            ENDTIME => '1710918615972',
            QUERYSTRING => 'fields @duration | filter @duration != 1000',
            LOGGROUPNAMES => '/aws/lambda/cloudwatch-test-1',
            LIMIT => '2'
            ))
```

## 授權資訊
<a name="connectors-cloudwatch-license-information"></a>

Amazon Athena CloudWatch 連接器專案是依據 [Apache-2.0 License](https://www.apache.org/licenses/LICENSE-2.0.html) 來授權的。

## 其他資源
<a name="connectors-cloudwatch-additional-resources"></a>

如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudwatch)。