を使用した証跡の Insights イベントの表示 AWS CLI

このセクションでは、 AWS CLI lookup-eventsおよび list-insights-data コマンドを使用して、Insights イベントを有効にした証跡の過去 90 日間の Insights イベントを検索する方法について説明します。証跡で CloudTrail Insights を有効にする方法については、「を使用した証跡の Insights イベントのログ記録 AWS CLI」を参照してください。

注記

lookup-events または list-insights-dataコマンドを使用してイベントデータストアの Insights イベントを検索することはできませんが、CloudTrail Lake には Insights イベントデータストアのサンプルクエリが多数用意されています。詳細については、「Insights イベントのサンプルクエリの表示」を参照してください。

lookup-events コマンドには以下のオプションがあります。

--end-time
--event-category
--max-results
--start-time
--lookup-attributes
--next-token
--generate-cli-skeleton
--cli-input-json

list-insights-data コマンドには以下のオプションがあります。

--end-time
--data-type
--max-results
--start-time
--dimensions
--next-token
--generate-cli-skeleton
--cli-input-json

の使用に関する一般的な情報については AWS Command Line Interface、 AWS Command Line Interface ユーザーガイドを参照してください。

前提条件

AWS CLI コマンドを実行するには、をインストールする必要があります AWS CLI。詳細については、「AWS CLIの使用を開始する」を参照してください。
AWS CLI バージョンが 1.6.6 より大きいことを確認します。CLI のバージョンを確認するには、コマンドラインで aws --version を実行します。
AWS CLI セッションのアカウント、リージョン、デフォルトの出力形式を設定するには、 aws configure コマンドを使用します。詳細については、「AWS コマンドラインインターフェイスの設定」を参照してください。
API コール率に関する Insights イベントを記録するには、証跡が write 管理イベントをログ記録している必要があります。API エラー率に関する Insights イベントを記録するには、証跡が read または write 管理イベントをログ記録している必要があります。

注記

CloudTrail AWS CLI コマンドでは、大文字と小文字が区別されます。

コマンドラインのヘルプを取得する

lookup-events のコマンドラインヘルプを表示するには、次のコマンドを入力します。


aws cloudtrail lookup-events help

管理イベントの Insights イベントの検索

最新の Insights イベントを 50 件表示するには、次のコマンドを入力します。


aws cloudtrail lookup-events --event-category insight

返されるイベントは、次の例のようになります。


{
    "NextToken": "kbOt5LlZe++mErCebpy2TgaMgmDvF1kYGFcH64JSjIbZFjsuvrSqg66b5YGssKutDYIyII4lrP4IDbeQdiObkp9YAlju3oXd12juEXAMPLE=", 
    "Events": [
        {
            "eventVersion": "1.09",
            "eventTime": "2024-12-11T16:52:00Z",
            "awsRegion": "us-east-1",
            "eventID": "18378b1e-3653-433d-ba1e-aa11a5958f0c",
            "eventType": "AwsCloudTrailInsight",
            "recipientAccountId": "888888888888",
            "sharedEventID": "fccb064f-dd07-4822-97c0-11115d8b91d4",
            "insightDetails": {
                "state": "Start",
                "eventSource": "cloudtrail.amazonaws.com",
                "eventName": "DescribeQuery",
                "insightType": "ApiErrorRateInsight",
                "errorCode": "QueryIdNotFoundException",
                "sourceEventCategory": "Management",
                "insightContext": {
                    "statistics": {
                        "baseline": {
                            "average": 0
                        },
                        "insight": {
                            "average": 1.2
                        },
                        "insightDuration": 5,
                        "baselineDuration": 11092
                    },
                    "attributions": [
                        {
                            "attribute": "userIdentityArn",
                            "insight": [
                                {
                                    "value": "arn:aws:sts::888888888888:assumed-role/Admin",
                                    "average": 1.2
                                }
                            ],
                            "baseline": []
                        },
                        {
                            "attribute": "userAgent",
                            "insight": [
                                {
                                    "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
                                    "average": 1.2
                                }
                            ],
                            "baseline": []
                        }
                    ]
                }
            },
            "eventCategory": "Insight"
        },
        {
            "eventVersion": "1.09",
            "eventTime": "2024-12-11T16:53:00Z",
            "awsRegion": "us-east-1",
            "eventID": "b32f10a0-f039-419a-bad7-e95468930a4f",
            "eventType": "AwsCloudTrailInsight",
            "recipientAccountId": "888888888888",
            "sharedEventID": "fccb064f-dd07-4822-97c0-11115d8b91d4",
            "insightDetails": {
                "state": "End",
                "eventSource": "cloudtrail.amazonaws.com",
                "eventName": "DescribeQuery",
                "insightType": "ApiErrorRateInsight",
                "errorCode": "QueryIdNotFoundException",
                "sourceEventCategory": "Management",
                "insightContext": {
                    "statistics": {
                        "baseline": {
                            "average": 0
                        },
                        "insight": {
                            "average": 6
                        },
                        "insightDuration": 1,
                        "baselineDuration": 11092
                    },
                    "attributions": [
                        {
                            "attribute": "userIdentityArn",
                            "insight": [
                                {
                                    "value": "arn:aws:sts::888888888888:assumed-role/Admin",
                                    "average": 6
                                }
                            ],
                            "baseline": []
                        },
                        {
                            "attribute": "userAgent",
                            "insight": [
                                {
                                    "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
                                    "average": 6
                                }
                            ],
                            "baseline": []
                        }
                    ]
                }
            },
            "eventCategory": "Insight"
        }
    ]
}

出力内の参照関連フィールドの説明については、このトピックの「参照の出力フィールド」を参照してください。Insights イベント内のフィールドの説明については、「証跡の Insights イベントの CloudTrail レコードコンテンツ」を参照してください。

データイベントの Insights イベントを検索する

最新の Insights イベントを 50 件表示するには、次のコマンドを入力します。


aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName

返されるイベントは、次の例のようになります。



    {  
    "NextToken": "kbOt5LlZe++mErCebpy2TgaMgmDvF1kYGFcH64JSjIbZFjsuvrSqg66b5YGssKutDYIyII4lrP4IDbeQdiObkp9YAlju3oXd12juEXAMPLE=",   
    "Events": [  
        {  
            "eventVersion": "1.09",  
            "eventTime": "2024-12-11T16:52:00Z",  
            "awsRegion": "us-east-2",  
            "eventID": "18378b1e-3653-433d-ba1e-aa11a5958f0c",  
            "eventType": "AwsCloudTrailInsight",  
            "recipientAccountId": "123456789012",  
            "sharedEventID": "fccb064f-dd07-4822-97c0-11115d8b91d4",  
            "insightDetails": {  
                "state": "Start",  
                "eventSource": "s3.amazonaws.com",  
                "eventName": "PutObject",  
                "insightType": "ApiErrorRateInsight",  
                "errorCode": "InvalidRequest",
                "sourceEventCategory": "Data",
                "insightContext": {  
                    "statistics": {  
                        "baseline": {  
                            "average": 0  
                        },  
                        "insight": {  
                            "average": 1.2  
                        },  
                        "insightDuration": 5,  
                        "baselineDuration": 11092  
                    },  
                    "attributions": [  
                        {  
                            "attribute": "userIdentityArn",  
                            "insight": [  
                                {  
                                    "value": "arn:aws:sts::123456789012:assumed-role/Admin",  
                                    "average": 1.2  
                                }  
                            ],  
                            "baseline": []  
                        },  
                        {  
                            "attribute": "userAgent",  
                            "insight": [  
                                {  
                                    "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",  
                                    "average": 1.2  
                                }  
                            ],  
                            "baseline": []  
                        }  
                    ]  
                },  

                "insightSource": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName"  
            },  
            "eventCategory": "Insight"  
        },  
        {  
            "eventVersion": "1.09",  
            "eventTime": "2024-12-11T16:53:00Z",  
            "awsRegion": "us-east-1",  
            "eventID": "b32f10a0-f039-419a-bad7-e95468930a4f",  
            "eventType": "AwsCloudTrailInsight",  
            "recipientAccountId": "123456789012",  
            "sharedEventID": "fccb064f-dd07-4822-97c0-11115d8b91d4",  
            "insightDetails": {  
                "state": "End",  
                "eventSource": "s3.amazonaws.com",  
                "eventName": "PutObject",  
                "insightType": "ApiErrorRateInsight",  
                "errorCode": "InvalidRequest",  
                "sourceEventCategory": "Data",  
                "insightContext": {  
                    "statistics": {  
                        "baseline": {  
                            "average": 0  
                        },  
                        "insight": {  
                            "average": 6  
                        },  
                        "insightDuration": 1,  
                        "baselineDuration": 11092  
                    },  
                    "attributions": [  
                        {  
                            "attribute": "userIdentityArn",  
                            "insight": [  
                                {  
                                    "value": "arn:aws:sts::123456789012:assumed-role/Admin",  
                                    "average": 6  
                                }  
                            ],  
                            "baseline": []  
                        },  
                        {  
                            "attribute": "userAgent",  
                            "insight": [  
                                {  
                                    "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",  
                                    "average": 6  
                                }  
                            ],  
                            "baseline": []  
                        }  
                    ]  
                }, 

                "insightSource": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName"    
            },  
            "eventCategory": "Insight"  
        }  
    ]  
}

管理イベントが返す Insights イベントの数を指定する

管理イベントが返す Insights イベントの数を指定するには、次のコマンドを入力します。


aws cloudtrail lookup-events --event-category insight --max-results <integer>

<integer> のデフォルト値は 50 です。有効な値は 1 から 50 です。次の例では、1 件の結果が返されています。


aws cloudtrail lookup-events --event-category insight --max-results 1

データイベントが返す Insights イベントの数を指定する

データイベントが返す Insights イベントの数を指定するには、次のコマンドを入力します。


aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --max-results <integer>

<integer> のデフォルト値は 50 です。有効な値は 1 から 50 です。次の例では、1 件の結果が返されています。


aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --max-results 1

時間範囲別の管理イベントの Insights イベントの検索

過去 90 日間の管理イベントの Insights イベントを検索できます。時間範囲を指定するには、次のコマンドを入力します。


aws cloudtrail lookup-events --event-category insight --start-time <timestamp> --end-time <timestamp>

--start-time <timestamp> を UTC で指定すると、指定された時刻かその後に発生した Insights イベントのみが返されます。指定された開始時刻が指定された終了時刻よりも後である場合は、エラーが返されます。

--end-time <timestamp> を UTC で指定すると、指定された時刻かその前に発生した Insights イベントのみが返されます。指定された終了時刻が指定された開始時刻よりも前である場合は、エラーが返されます。

デフォルトの開始時刻は、過去 90 日間のうち、データが利用できる最も早い日付です。デフォルトの終了時刻は、現在の時刻に最も近いイベント発生時刻です。

すべてのタイムスタンプは UTC で表示されます。

時間範囲によるデータイベントの Insights イベントの検索

過去 90 日間のデータイベントの Insights イベントを検索できます。時間範囲を指定するには、次のコマンドを入力します。


aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --start-time <timestamp> --end-time <timestamp>

すべてのタイムスタンプは UTC で表示されます。

属性による管理イベントの Insights イベントの検索

属性でフィルタリングするには、次のコマンドを入力します。


aws cloudtrail lookup-events --event-category insight --lookup-attributes AttributeKey=<attribute>,AttributeValue=<string>

各 lookup-events コマンドに対し、属性キーと値のペアを 1 つだけ指定できます。以下に、AttributeKey の有効な Insights イベント値を示します。値名では大文字と小文字が区別されます。

EventId
EventName
EventSource

AttributeValue の最大長は 2,000 文字です。次の文字 (「_」、「」、「,」、「\\n」) は、2,000 文字の制限のうちの 2 文字としてカウントされます。

属性参照の例

次のコマンド例では、EventName の値が PutRule である Insights イベントが返されます。


aws cloudtrail lookup-events --event-category insight --lookup-attributes AttributeKey=EventName, AttributeValue=PutRule

次のコマンド例では、EventId の値が b5cc8c40-12ba-4d08-a8d9-2bceb9a3e002 である Insights イベントが返されます。


aws cloudtrail lookup-events --event-category insight --lookup-attributes AttributeKey=EventId, AttributeValue=b5cc8c40-12ba-4d08-a8d9-2bceb9a3e002

次のコマンド例では、EventSource の値が iam.amazonaws.com である Insights イベントが返されます。


aws cloudtrail lookup-events --event-category insight --lookup-attributes AttributeKey=EventSource, AttributeValue=iam.amazonaws.com

ディメンション別のデータイベントの Insights イベントの検索

ディメンションでフィルタリングするには、次のコマンドを入力します。


aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName 
        --dimensions <DimensionKey>=<DimensionValue>

list-insights-events コマンドごとに指定できるディメンションのキーと値のペアは 1 つだけです。以下に、DimensionKey の有効な Insights イベント値を示します。値名では大文字と小文字が区別されます。

EventId
EventName
EventSource

DimensionValue の最大長は 2,000 文字です。次の文字 (「_」、「」、「,」、「\\n」) は、2,000 文字の制限のうちの 2 文字としてカウントされます。

ディメンションルックアップの例

次のコマンド例では、EventName の値が PutObject である Insights イベントが返されます。


aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --dimensions EventName=PutObject

次のコマンド例では、EventId の値が b5cc8c40-12ba-4d08-a8d9-2bceb9a3e002 である Insights イベントが返されます。


aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --dimensions EventId=b5cc8c40-12ba-4d08-a8d9-2bceb9a3e002

次のコマンド例では、EventSource の値が s3.amazonaws.com である Insights イベントが返されます。


aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --dimensions EventSource=s3.amazonaws.com

管理イベントの Insights イベントの結果の次のページを指定する

lookup-events コマンドの次の結果ページを取得するには、次のコマンドを入力します。


aws cloudtrail lookup-events --event-category insight <same parameters as previous command> --next-token=<token>

このコマンドでは、<token> の値は、前のコマンドの出力の最初のフィールドから取得されます。

コマンド内で --next-token を使用する場合は、前のコマンドと同じパラメータを使用する必要があります。たとえば、次のコマンドを実行したとします。


aws cloudtrail lookup-events --event-category insight --lookup-attributes AttributeKey=EventName, AttributeValue=PutRule

次の結果ページを取得する場合、コマンドは次のようになります。


aws cloudtrail lookup-events --event-category insight --lookup-attributes AttributeKey=EventName,AttributeValue=PutRule --next-token=EXAMPLEZe++mErCebpy2TgaMgmDvF1kYGFcH64JSjIbZFjsuvrSqg66b5YGssKutDYIyII4lrP4IDbeQdiObkp9YAlju3oXd12juEXAMPLE=

管理イベントの Insights イベントの結果の次のページを指定する

list-insights-data コマンドの次の結果ページを取得するには、次のコマンドを入力します。


aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName<same parameters as previous command> --next-token=<token>

このコマンドでは、<token> の値は、前のコマンドの出力の最初のフィールドから取得されます。


aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --dimensions EventName=PutObject

次の結果ページを取得する場合、コマンドは次のようになります。


aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --dimensions EventName=PutObject --next-token=EXAMPLEZe++mErCebpy2TgaMgmDvF1kYGFcH64JSjIbZFjsuvrSqg66b5YGssKutDYIyII4lrP4IDbeQdiObkp9YAlju3oXd12juEXAMPLE=

管理イベントの Insights イベントのファイルから JSON 入力を取得する

AWS CLI 一部の AWS サービスのには、JSON テンプレートの生成--cli-input-jsonに使用できる --generate-cli-skeletonとの 2 つのパラメータがあり、これを変更して--cli-input-jsonパラメータへの入力として使用できます。このセクションでは、これらのパラメータを aws cloudtrail lookup-events で使用する方法について説明します。詳細については、「AWS CLI スケルトンと入力ファイル」を参照してください。

JSON 入力をファイルから取得して Insights イベントを参照するには

次の例のように、lookup-events の出力をファイルにリダイレクトして、--generate-cli-skeleton で使用するための入力テンプレートを作成します。


aws cloudtrail lookup-events --event-category insight --generate-cli-skeleton > LookupEvents.txt

生成されるテンプレートファイル (この場合、LookupEvents.txt) は次のようになります。



{
    "LookupAttributes": [
        {
            "AttributeKey": "",
            "AttributeValue": ""
        }
    ],
    "StartTime": null,
    "EndTime": null,
    "MaxResults": 0,
    "NextToken": ""
}

テキストエディタを使用し、必要に応じて JSON を変更します。JSON 入力には、指定された値のみが含まれている必要があります。

重要
空の値や Null 値は、使用する前にテンプレートからすべて削除する必要があります。

次の例では、時間範囲と、返される結果の最大数を指定しています。
```
{
    "StartTime": "2023-11-01",
    "EndTime": "2023-12-12",
    "MaxResults": 10
}                         
```
編集したファイルを入力として使用するには、次の例のように、構文 --cli-input-json file://<filename> を使用します。
```
aws cloudtrail lookup-events --event-category insight --cli-input-json file://LookupEvents.txt
```

注記

--cli-input-json と同じコマンドラインで、他の引数を使用することもできます。

データイベントの Insights イベントのファイルから JSON 入力を取得する

AWS CLI 一部の AWS サービスのには、JSON テンプレートの生成--cli-input-jsonに使用できる --generate-cli-skeletonとの 2 つのパラメータがあり、これを変更して--cli-input-jsonパラメータへの入力として使用できます。このセクションでは、これらのパラメータを aws cloudtrail list-insights-data で使用する方法について説明します。詳細については、「AWS CLI スケルトンと入力ファイル」を参照してください。

JSON 入力をファイルから取得して Insights イベントを参照するには

次の例のように、list-insights-data の出力をファイルにリダイレクトして、--generate-cli-skeleton で使用するための入力テンプレートを作成します。


aws cloudtrail list-insights-data --data-type InsightsEvents --generate-cli-skeleton > ListInsightsData.txt

生成されたテンプレートファイル (この場合は ListInsightsData.txt) は次のようになります。


{  
   "InsightSource": "",
    "DataType": "InsightsEvents", 
    "Dimensions":
    {
        "KeyName": ""
    },
    "StartTime": null,
    "EndTime": null,
    "MaxResults": 0,
    "NextToken": ""
}

テキストエディタを使用し、必要に応じて JSON を変更します。JSON 入力には、指定された値のみが含まれている必要があります。

重要

空の値や Null 値は、使用する前にテンプレートからすべて削除する必要があります。

次の例では、時間範囲と、返される結果の最大数を指定しています。



{
    
   "InsightSource": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName", 
    "DataType": "InsightsEvents", 
    "Dimensions":
    {
        "EventName": "PutObject"
    },
    "StartTime": "2025-11-01",
    "EndTime": "2025-11-05",
    "MaxResults": 1
}

編集したファイルを入力として使用するには、次の例のように、構文 --cli-input-json file://<filename> を使用します。
```
aws cloudtrail list-insights-data --data-type InsightsEvents --cli-input-json file://ListInsightsData.txt
```

注記

--cli-input-json と同じコマンドラインで、他の引数を使用することもできます。

参照の出力フィールド

イベント

指定された参照属性と時間範囲に基づく参照イベントのリストです。イベントリストは時刻でソートされ、最新のイベントが最初に表示されます。各エントリには、参照リクエストに関する情報と、取得された CloudTrail イベントの文字列表現が含まれます。

以下のエントリは、各参照イベント内のフィールドです。

CloudTrailEvent

返されたイベントのオブジェクト表現を含んだ JSON 文字列です。返される各要素については、「 Record Body Contents」を参照してください。

EventId

返されたイベントの GUID を含んだ文字列です。

EventName

返されたイベントの名前を含んだ文字列です。

EventSource

リクエストが行われた AWS サービス。

EventTime

イベントの日時です (UNIX 時刻形式)。

リソース

返されたイベントによって参照されるリソースのリストです。各リソースエントリは、リソースタイプとリソース名を指定します。

ResourceName

イベントによって参照されるリソースの名前を含んだ文字列です。

ResourceType

イベントによって参照されるリソースのタイプを含んだ文字列です。リソースタイプを特定できない場合は、null が返されます。

ユーザー名

返されたイベントに対するアカウントのユーザー名を含んだ文字列です。

NextToken

前の lookup-events コマンドから次の結果ページを取得するための文字列です。トークンを使用するには、パラメータが元のコマンドと同じである必要があります。NextToken エントリが出力に表示されない場合、返す結果はそれ以上存在しません。

CloudTrail Insights イベントの詳細については、このガイドの「CloudTrail Insights の使用」を参照してください。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

コンソールを使用して証跡の Insights イベントを表示する

イベントデータストアの Insights イベントの表示

を使用した証跡の Insights イベントの表示 AWS CLI

注記

目次

前提条件

注記

コマンドラインのヘルプを取得する

管理イベントの Insights イベントの検索

データイベントの Insights イベントを検索する

管理イベントが返す Insights イベントの数を指定する

データイベントが返す Insights イベントの数を指定する

時間範囲別の管理イベントの Insights イベントの検索

時間範囲によるデータイベントの Insights イベントの検索

属性による管理イベントの Insights イベントの検索

属性参照の例

ディメンション別のデータイベントの Insights イベントの検索

ディメンションルックアップの例

管理イベントの Insights イベントの結果の次のページを指定する

管理イベントの Insights イベントの結果の次のページを指定する

管理イベントの Insights イベントの ファイルから JSON 入力を取得する

JSON 入力をファイルから取得して Insights イベントを参照するには

重要

注記

データイベントの Insights イベントの ファイルから JSON 入力を取得する

JSON 入力をファイルから取得して Insights イベントを参照するには

重要

注記

参照の出力フィールド

管理イベントの Insights イベントのファイルから JSON 入力を取得する

データイベントの Insights イベントのファイルから JSON 入力を取得する