View a markdown version of this page

lookup - Amazon CloudWatch Logs
ルックアップテーブルの作成と管理検索のクエリ構文

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

lookup

を使用してlookup、ルックアップテーブルからの参照データでクエリ結果を強化します。ルックアップテーブルには、Amazon CloudWatch Logs にアップロードする CSV データが含まれています。クエリが実行されると、 lookup コマンドはログイベントのフィールドをルックアップテーブルのフィールドと照合し、指定された出力フィールドを結果に追加します。

ユーザー IDsユーザーの詳細にマッピングする、製品コードを製品情報にマッピングする、エラーコードをエラーの説明にマッピングするなどのデータエンリッチメントシナリオには、ルックアップテーブルを使用します。

ルックアップテーブルの作成と管理

クエリで lookup コマンドを使用する前に、ルックアップテーブルを作成する必要があります。ルックアップテーブルは、CloudWatch コンソールから、または Amazon CloudWatch Logs API を使用して作成および管理できます。

ルックアップテーブルを作成するには (コンソール)

  1. CloudWatch コンソールの https://console.aws.amazon.com/cloudwatch/ を開いてください。

  2. ナビゲーションペインで、設定を選択し、ログタブを選択します。

  3. Lookup tables までスクロールし、Manage を選択します。

  4. ルックアップテーブルの作成を選択します。

  5. ルックアップテーブルの名前を入力します。名前には、英数字、ハイフン、アンダースコアのみを含めることができます。

  6. (オプション) 説明を入力します。

  7. CSV ファイルをアップロードします。ファイルには、列名を含むヘッダー行を含める必要があり、UTF-8 エンコーディングを使用し、10 MB を超えることはできません。

  8. (オプション) テーブルデータを暗号化する AWS KMS キーを指定します。

  9. [作成] を選択します。

ルックアップテーブルを作成したら、CloudWatch Logs Insights クエリエディタで表示できます。ルックアップテーブルタブを選択して、使用可能なテーブルとそのフィールドを参照します。

ルックアップテーブルを更新するには、テーブルを選択し、アクション、更新を選択します。新しい CSV ファイルをアップロードして、既存のすべてのコンテンツを置き換えます。ルックアップテーブルを削除するには、アクション、削除を選択します。

注記

アカウントごとに、 ごとに最大 100 個のルックアップテーブルを作成できます AWS リージョン。CSV ファイルは最大 10 MB です。Amazon CloudWatch Logs API を使用してルックアップテーブルを管理することもできます。詳細については、Amazon CloudWatch Logs API リファレンスの「CreateLookupTable」を参照してください。

注記

ルックアップテーブルが KMS キーで暗号化されている場合、呼び出し元は、そのルックアップテーブルを参照するクエリで StartQuery API を使用するには、キー (ルックアップテーブルの暗号化に使用される KMS キー) に対するkms:Decryptアクセス許可を持っている必要があります。詳細については、「を使用して CloudWatch Logs のルックアップテーブルを暗号化する AWS Key Management Service」を参照してください。

検索のクエリ構文

コマンド構造

このコマンドの形式を次に示します。

lookup table match-fields output-mode output-field[,...]

コマンドは次の引数を使用します。

  • table – 使用するルックアップテーブルの名前。

  • match-fields – ログイベントをルックアップテーブルと照合する 1 つ以上のフィールドを指定します。次のいずれかの形式を使用できます。

    • lookup-field as log-field [,...] – ルックアップテーブルの列名がログイベントフィールド名と異なるas場合に使用します。たとえば、 はルックアップテーブルのip_address列をログイベントの srcAddrフィールドとip_address as srcAddr照合します。

    • lookup-field [,...] – ログイベントフィールド名がルックアップテーブルの列名と同じ場合、フィールド名を直接省略asして指定できます。たとえば、 は両方の列を同じ名前のログイベントフィールドとdepartment, role照合します。

    複数の一致フィールドを指定する場合、結果を生成するには、ルックアップテーブルの行がすべてのフィールドと一致する必要があります (AND ロジック）。

  • output-mode – 出力フィールドを結果に追加する方法を指定します。以下のいずれかを使用します。

    • OUTPUT – 出力フィールドを結果に追加します。ログイベントに同じ名前のフィールドがすでに存在する場合、ルックアップテーブル値で上書きされます。一致が見つからない場合、 フィールドは null に設定されます。

    • OUTPUTNEW – フィールドがログイベントにまだ存在しない場合にのみ、出力フィールドを結果に追加します。フィールドにすでに値がある場合、元の値は保持されます。一致が見つからない場合、 フィールドは変更されません。

  • output-field – 結果に追加するルックアップテーブルの 1 つ以上のフィールド。

例: ユーザーの詳細を使用してログイベントを強化する

id フィールドを含むイベントを含むロググループと、列 id、、、nameemailおよび user_dataを含む という名前のルックアップテーブルがあるとしますdepartment。次のクエリは、各ログイベントをルックアップテーブルのユーザー名、E メール、部門で強化します。

fields action, status, name, email, department
| lookup user_data id OUTPUT name, email, department
例: 集計でルックアップを使用する

集計関数でルックアップ出力フィールドを使用できます。次のクエリは、ユーザーの詳細でログイベントを強化し、E メールアドレス別にグループ化されたイベントをカウントします。

fields user_id, action, username, email, department
| lookup user_data user_id OUTPUT username, email, department
| stats count(*) by email
例: フィルターでルックアップを使用する

ルックアップによって返されたフィールドに基づいて結果をフィルタリングできます。次のクエリはログイベントを強化し、特定の部門のイベントのみを表示するようにフィルタリングします。

fields user_id, action
| lookup user_data user_id OUTPUT username, email, department
| filter department = "Engineering"
例: OUTPUTNEW を使用して上書きせずに強化する

ログイベントに既にhostnameフィールドが含まれているが、場合によっては空である場合は、 OUTPUTNEW を使用して、既存の値を上書きせずに欠損値を入力します。

fields srcAddr, hostname
| lookup known_hosts ip_address as srcAddr OUTPUTNEW hostname, region
例: 複数の一致フィールドでルックアップを使用する

複数のフィールドで一致させることができます。次のクエリは、 srcAddrと の両方をルックアップテーブルdstPortと照合して、既知のネットワークサービスを識別します。

fields @timestamp, srcAddr, dstAddr, dstPort
| lookup network_services ip_address as srcAddr, port as dstPort OUTPUT service_name, owner
| filter ispresent(service_name)
例: 一致するフィールド名でルックアップを使用する

ログイベントフィールド名がルックアップテーブルの列名と正確に一致する場合は、asキーワードを省略できます。次のクエリは、 フィールドdepartmentと roleフィールドの両方をルックアップテーブルと直接照合します。

fields @timestamp, department, role
| lookup employees department, role OUTPUT office, manager