# Amazon Athena CloudWatch コネクタ
Amazon Athena CloudWatch コネクタは、Amazon Athena が CloudWatch とやり取りすることを可能にして、ログデータを SQL でクエリできるようにします。
このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元化しません。接続設定は Lambda を介して行われます。
このコネクタは、LogGroups をスキーマとして、および各 LogStream をテーブルとしてマップします。また、コネクタにより、LogGroup 内のすべての LogStream が含まれている特別な `all_log_streams` ビューもマップされます。このビューでは、各 LogStream を個別に検索するのではなく、LogGroup 内のすべてのログを一度にクエリできます。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## パラメータ
このセクションのパラメータを使用して CloudWatch コネクタを設定します。
### Glue 接続 (推奨)
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 のみをサポートします。
### レガシー接続
+ **spill\$1bucket** – Lambda 関数の上限を超えたデータに対して、Amazon S3 バケットを指定します。
+ **spill\$1prefix** – (オプション) 指定された `athena-federation-spill` という `spill_bucket` の、デフォルトのサブフォルダに設定します。このロケーションで、Amazon S3 の[ストレージライフサイクル](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)を設定し、あらかじめ決められた日数または時間数以上経過したスピルを削除することをお勧めします。
+ **spill\$1put\$1request\$1headers** – (オプション) スピリングに使用されるAmazon S3 の `putObject` リクエスト (例:`{"x-amz-server-side-encryption" : "AES256"}`) に関する、 JSON でエンコードされたリクエストヘッダーと値のマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。
+ **kms\$1key\$1id** – (オプション) デフォルトでは、Amazon S3 に送信されるすべてのデータは、AES-GCM で認証された暗号化モードとランダムに生成されたキーを使用して暗号化されます。KMS が生成したより強力な暗号化キー (たとえば `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`) を Lambda 関数に使用させる場合は、KMS キー ID を指定します。
+ **disable\$1spill\$1encryption** – (オプション) `True` に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は `False` です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先で[サーバー側の暗号化](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)を使用している場合に、パフォーマンスが向上します。
コネクタでは、CloudWatch から [Amazon Athena クエリフェデレーション SDK](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-federation-sdk) の `ThrottlingInvoker` コンストラクトを介してスロットリングされるイベントの処理用として、[AIMD の輻輳 (ふくそう) 制御](https://en.wikipedia.org/wiki/Additive_increase/multiplicative_decrease) もサポートしています。以下のオプションの環境変数のいずれかを設定することで、デフォルトのスロットリング動作を微調整できます。
+ **throttle\$1initial\$1delay\$1ms** – 最初の輻輳イベントの後に適用される最初の呼び出し遅延。デフォルト値は 10 ミリ秒です。
+ **throttle\$1max\$1delay\$1ms** – 呼び出し間の最大遅延。これを 1000 ミリ秒で除算することで、TPS を算出できます。デフォルト値は 1000 ミリ秒です。
+ **throttle\$1decrease\$1factor** – Athena が呼び出しのレートを低減する要因。デフォルトは 0.5 です。
+ **throttle\$1increase\$1ms** – Athena がコール遅延を低減させた際のレート。デフォルト値は 10 ミリ秒です。
## データベースとテーブル
このコネクタは、LogGroups をスキーマ (つまりデータベース) として、また、各 LogStream をテーブルとしてマップします。また、コネクタにより、LogGroup 内のすべての LogStream が含まれている特別な `all_log_streams` ビューもマップされます。このビューでは、各 LogStream を個別に検索するのではなく、LogGroup 内のすべてのログを一度にクエリできます。
Athena CloudWatch コネクタによってマッピングされるすべてのテーブルには、次のスキーマが含まれています。このスキーマにより、CloudWatch Logs が提供するフィールドとのマッチングが行われます。
+ **log\$1stream** – 対象の行を提供する LogStream の名前が含まれている `VARCHAR`。
+ **time** – ログ行が生成されたエポックタイムを含む `INT64`。
+ **message** – ログメッセージを含む `VARCHAR`。
**例**
以下の例では、指定された LogStream に対する `SELECT` クエリの実行方法を示しています
```
SELECT *
FROM "lambda:cloudwatch_connector_lambda_name"."log_group_path"."log_stream_name"
LIMIT 100
```
以下の例では、`all_log_streams`ビューを使用して、指定された LogGroup 内のすべての LogStreams に対してクエリを実行する方法を示しています。
```
SELECT *
FROM "lambda:cloudwatch_connector_lambda_name"."log_group_path"."all_log_streams"
LIMIT 100
```
## 必要な許可
このコネクタが必要とする 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 クエリが終了した際に fast-fail を実行します。
+ **CloudWatch Logs Read/Write** – コネクタは、ログデータの読み取りと診断ログの書き込みのために、このアクセス許可を使用します。
## パフォーマンス
Athena CloudWatch コネクタは、クエリが必要とするログストリームのスキャンを並列化することで、CloudWatch に対するクエリの最適化を試みます。フィルタで特定の期間を指定する場合、Lambda 関数内と CloudWatch Logs 内の両方で述語のプッシュダウンが実行されます。
最高のパフォーマンスを得るには、ロググループ名とログストリーム名には小文字のみを使用してください。大文字と小文字が混在すると、コネクタは大文字と小文字を区別しない検索を実行するため、計算量が多くなります。
**注記**
CloudWatch コネクタは、大文字のデータベース名をサポートしていません。
## パススルークエリ
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'
))
```
## ライセンス情報
Amazon Athena CloudWatch コネクタプロジェクトは、[Apache-2.0 ライセンス](https://www.apache.org/licenses/LICENSE-2.0.html)の下で使用許諾されています。
## その他のリソース
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudwatch)を参照してください。