Amazon Athena CloudWatch コネクタ - Amazon Athena
前提条件パラメータデータベースとテーブル必要な許可パフォーマンスパススルークエリライセンス情報追加リソース

Amazon Athena CloudWatch コネクタ

Amazon Athena CloudWatch コネクタは、Amazon Athena が CloudWatch とやり取りすることを可能にして、ログデータを SQL でクエリできるようにします。

このコネクタは、LogGroups をスキーマとして、および各 LogStream をテーブルとしてマップします。また、コネクタにより、LogGroup 内のすべての LogStream が含まれている特別な all_log_streams ビューもマップされます。このビューでは、各 LogStream を個別に検索するのではなく、LogGroup 内のすべてのログを一度にクエリできます。

前提条件

パラメータ

このセクションの Lambda 環境変数により、CloudWatch コネクタを設定します。

  • spill_bucket – Lambda 関数の上限を超えたデータに対して、Amazon S3 バケットを指定します。

  • spill_prefix – (オプション) 指定された athena-federation-spill という spill_bucket の、デフォルトのサブフォルダに設定します。このロケーションで、Amazon S3 のストレージライフサイクルを設定し、あらかじめ決められた日数または時間数以上経過したスピルを削除することをお勧めします。

  • spill_put_request_headers – (オプション) スピリングに使用されるAmazon S3 の putObject リクエスト (例:{"x-amz-server-side-encryption" : "AES256"}) に関する、 JSON でエンコードされたリクエストヘッダーと値のマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「PutObject」を参照してください。

  • kms_key_id – (オプション) デフォルトでは、Amazon S3 に送信されるすべてのデータは、AES-GCM で認証された暗号化モードとランダムに生成されたキーを使用して暗号化されます。KMS が生成したより強力な暗号化キー (たとえば a7e63k4b-8loc-40db-a2a1-4d0en2cd8331) を Lambda 関数に使用させる場合は、KMS キー ID を指定します。

  • disable_spill_encryption – (オプション) True に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は False です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先でサーバー側の暗号化を使用している場合に、パフォーマンスが向上します。

コネクタでは、CloudWatch から Amazon Athena クエリフェデレーション SDK の ThrottlingInvoker コンストラクトを介してスロットリングされるイベントの処理用として、AIMD の輻輳 (ふくそう) 制御 もサポートしています。以下のオプションの環境変数のいずれかを設定することで、デフォルトのスロットリング動作を微調整できます。

  • throttle_initial_delay_ms – 最初の輻輳イベントの後に適用される最初の呼び出し遅延。デフォルト値は 10 ミリ秒です。

  • throttle_max_delay_ms – 呼び出し間の最大遅延。これを 1000 ミリ秒で除算することで、TPS を算出できます。デフォルト値は 1000 ミリ秒です。

  • throttle_decrease_factor – Athena が呼び出しのレートを低減する要因。デフォルトは 0.5 です。

  • throttle_increase_ms – Athena がコール遅延を低減させた際のレート。デフォルト値は 10 ミリ秒です。

データベースとテーブル

このコネクタは、LogGroups をスキーマ (つまりデータベース) として、また、各 LogStream をテーブルとしてマップします。また、コネクタにより、LogGroup 内のすべての LogStream が含まれている特別な all_log_streams ビューもマップされます。このビューでは、各 LogStream を個別に検索するのではなく、LogGroup 内のすべてのログを一度にクエリできます。

Athena CloudWatch コネクタによってマッピングされるすべてのテーブルには、次のスキーマが含まれています。このスキーマにより、CloudWatch Logs が提供するフィールドとのマッチングが行われます。

  • log_stream – 対象の行を提供する 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 ファイルの Policies セクションを参照してください。次のリストは、必要なアクセス権限をまとめたものです。

  • Amazon S3 への書き込みアクセス – 大規模なクエリからの結果をスピルするために、コネクタは Amazon S3 内のロケーションへの書き込みアクセス権限を必要とします。

  • Athena GetQueryExecution – コネクタはこの権限を使用して、アップストリームの Athena クエリが終了した際に fast-fail を実行します。

  • CloudWatch Logs Read/Write – コネクタは、ログデータの読み取りと診断ログの書き込みのために、このアクセス許可を使用します。

パフォーマンス

Athena CloudWatch コネクタは、クエリが必要とするログストリームのスキャンを並列化することで、CloudWatch に対するクエリの最適化を試みます。フィルタで特定の期間を指定する場合、Lambda 関数内と CloudWatch Logs 内の両方で述語のプッシュダウンが実行されます。

最高のパフォーマンスを得るには、ロググループ名とログストリーム名には小文字のみを使用してください。大文字と小文字が混在すると、コネクタは大文字と小文字を区別しない検索を実行するため、計算量が多くなります。

パススルークエリ

CloudWatch コネクタは、CloudWatch Logs Insights クエリ構文を使用するパススルークエリをサポートします。CloudWatch Logs Insights の詳細については、「Amazon CloudWatch Logs ユーザーガイド」の「CloudWatch Logs Insights でログデータを分析する」を参照してください。

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 ライセンスの下で使用許諾されています。

追加リソース

このコネクタに関するその他の情報については、GitHub.com で対応するサイトを参照してください。