Logging Insights events - Amazon CloudTrail
Understanding Insights events deliveryLogging Insights events with the Amazon Web Services Management ConsoleLogging Insights events with the Amazon Command Line InterfaceLogging Insights events with the Amazon SDKs
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Logging Insights events

Amazon CloudTrail Insights help Amazon users identify and respond to unusual activity associated with API calls and API error rates by continuously analyzing CloudTrail management events. CloudTrail Insights analyzes your normal patterns of API call volume and API error rates, also called the baseline, and generates Insights events when the call volume or error rates are outside normal patterns. Insights events on API call volume are generated for write management APIs, and Insights events on API error rate are generated for both read and write management APIs.

Note

To log Insights events on API call volume, the trail or event data store must log write management events. To log Insights events on API error rate, the trail or event data store must log read or write management events.

CloudTrail Insights analyzes management events that occur in a single Region, not globally. A CloudTrail Insights event is generated in the same Region as its supporting management events are generated.

Additional charges apply for Insights events. You will be charged separately if you enable Insights for both trails and event data stores. For more information, see Amazon CloudTrail Pricing.

Understanding Insights events delivery

Unlike other types of events that CloudTrail captures, Insights events are logged only when CloudTrail detects changes in your account's API usage that differ significantly from the account's typical usage patterns.

Where CloudTrail delivers events and how long it takes to receive Insights events differs between trails and event data stores.

Insights events delivery for trails

If you've enabled Insights events on a trail and CloudTrail detects unusual activity, CloudTrail delivers Insights events to the /CloudTrail-Insight folder in the chosen destination S3 bucket for your trail. After you enable CloudTrail Insights for the first time on a trail, it can take up to 36 hours for CloudTrail to deliver the first Insights event, if unusual activity is detected.

If you turn off Insights events logging on a trail and then re-enable Insights events, or stop and restart logging on a trail, it can take up to 36 hours for CloudTrail to restart delivery of Insights events, if unusual activity is detected.

Insights events delivery for event data stores

If you've enabled Insights events on a source event data store, CloudTrail delivers Insights events to the destination event data store. After you enable CloudTrail Insights for the first time on the source event data store, it can take up to 7 days for CloudTrail to deliver the first Insights event to the destination event data store, if unusual activity is detected.

If you turn off Insights events logging on a source event data store and then re-enable Insights events, or stop and restart event ingestion on a source event data store, it can take up to 7 days for CloudTrail to restart delivery of Insights events, if unusual activity is detected. Additional charges apply for ingesting Insights events in CloudTrail Lake. You will be charged separately if you enable Insights for both trails and event data stores. For information about CloudTrail pricing, see Amazon CloudTrail Pricing.

Logging Insights events with the Amazon Web Services Management Console

You can enable Insights events on a trail using the console.

Enabling CloudTrail Insights events on an existing trail

Use the following procedure to enable CloudTrail Insights events on an existing trail. By default, Insights events are not enabled.

  1. In the left navigation pane of the CloudTrail console, open the Trails page, and choose a trail name.

  2. In Insights events choose Edit.

    Note

    Additional charges apply for logging Insights events. For CloudTrail pricing, see Amazon CloudTrail Pricing.

  3. In Event type, choose Insights events.

  4. In Insights events, under Choose Insights types, choose API call rate, API error rate, or both. Your trail must be logging Write management events to log Insights events for API call rate. Your trail must be logging Read or Write management events to log Insights events for API error rate.

  5. Choose Save changes to save your changes.

It can take up to 36 hours for CloudTrail to deliver the first Insights events, if unusual activity is detected.

Logging Insights events with the Amazon Command Line Interface

You can configure your trails and event data stores to log Insights events using the Amazon CLI.

Note

To log Insights events on API call volume, the trail must log write management events. To log Insights events on API error rate, the trail must log read or write management events.

Logging Insights events for a trail using the Amazon CLI

To view whether your trail is logging Insights events, run the get-insight-selectors command.

aws cloudtrail get-insight-selectors --trail-name TrailName

The following result shows the default settings for a trail. By default, trails don't log Insights events. The InsightType attribute value is empty, and no Insight event selectors are specified, because Insights event collection is not enabled.

If you do not add Insights selectors, the get-insight-selectors command returns the following error message: "An error occurred (InsightNotEnabledException) when calling the GetInsightSelectors operation: Trail name does not have Insights enabled. Edit the trail settings to enable Insights, and then try the operation again."

{
  "InsightSelectors": [ ],
  "TrailARN": "arn:aws:cloudtrail:us-east-1:123456789012:trail/TrailName"
}

To configure your trail to log Insights events, run the put-insight-selectors command. The following example shows how to configure your trail to include Insights events. Insights selector values can be ApiCallRateInsight, ApiErrorRateInsight, or both.

aws cloudtrail put-insight-selectors --trail-name TrailName --insight-selectors '[{"InsightType": "ApiCallRateInsight"},{"InsightType": "ApiErrorRateInsight"}]'

The following result shows the Insights event selector that is configured for the trail.

{
  "InsightSelectors":
      [
         {
            "InsightType": "ApiErrorRateInsight"
         },
         {
            "InsightType": "ApiCallRateInsight"
         }
      ],
  "TrailARN": "arn:aws:cloudtrail:us-east-1:123456789012:trail/TrailName"
}

Logging Insights events with the Amazon SDKs

Run the GetInsightSelectors operation to see whether your trail enables Insights events. You can configure your trails to enable Insights events with the PutInsightSelectors operation. For more information, see the Amazon CloudTrail API Reference.