How CloudTrail works

You automatically have access to the CloudTrail Event history when you create your AWS account. The Event history provides a viewable, searchable, downloadable, and immutable record of the past 90 days of recorded management events in an AWS Region.

For an ongoing record of events in your AWS account past 90 days, create a trail or a CloudTrail Lake event data store.

CloudTrail Event history

You can easily view the last 90 days of management events in the CloudTrail console by going to the Event history page. You can also view the event history by running the aws cloudtrail lookup-events command, or the LookupEvents API operation. You can search events in Event history by filtering for events on a single attribute. For more information, see Working with CloudTrail event history.

The Event history is not connected to any trails or event data stores that exist in your account and is not affected by configuration changes you make to your trails and event data stores.

There are no CloudTrail charges for viewing the Event history page or running the lookup-events command.

CloudTrail Lake and event data stores

You can create an event data store to log CloudTrail events (management events, data events, network activity events), CloudTrail Insights events, AWS Audit Manager evidence, AWS Config configuration items, or events outside of AWS.

Event data stores can log events from the current AWS Region, or from all AWS Regions in your AWS account. Event data stores that you are using to log Integration events from outside AWS must be for a single Region only; they cannot be multi-Region event data stores.

If you have created an organization in AWS Organizations, you can create an organization event data store that logs all events for all AWS accounts in that organization. Organization event data stores can apply to all AWS Regions, or the current Region. Organization event data stores must be created using the management account or delegated administrator account, and when specified as applying to an organization, are automatically applied to all member accounts in the organization. Member accounts cannot see the organization event data store, nor can they modify or delete it. Organization event data stores cannot be used to collect events from outside of AWS. For more information, see Understanding organization event data stores.

By default, all events in an event data store are encrypted by CloudTrail. When you configure an event data store, you can choose to use your own AWS KMS key. Using your own KMS key incurs AWS KMS costs for encryption and decryption. After you associate an event data store with a KMS key, the KMS key cannot be removed or changed. For more information, see Encrypting CloudTrail log files with AWS KMS keys (SSE-KMS).

The following table provides information about tasks you can perform on event data stores.

Task	Description
View and create dashboards	You can use CloudTrail Lake dashboards to see event trends for the event data stores in your account. You can view managed dashboards, create custom dashboards, and enable the Highlights dashboard to see highlights for your event data curated and managed by CloudTrail Lake.
Log management events	Configure your event data store to log read-only, write-only, or all management events. By default, event data stores log management events. You can filter management events on the following advanced event selector fields: eventName, eventSource, eventType, readOnly, sessionCredentialFromConsole, and userIdentity.arn.
Log data events	You can use advanced event selectors to create fine-grained selectors to log only those data events of interest. For example, you can filter on the eventName field to include or exclude logging of specific API calls, which can help control costs. For more information, see Filtering data events by using advanced event selectors.
Log network activity events	Configure your event data store to log network activity events. You can use advanced event selectors to filter on the eventName, errorCode, and vpcEndpointId fields to log only those events of interest.
Log Insights events	Configure your event data stores to log Insights events to help you identify and respond to unusual activity associated with management API calls. For more information, see Working with CloudTrail Insights. 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 AWS CloudTrail Pricing.
Copy trail events	You can copy trail events to a new or existing event data store to create a point-in-time snapshot of events logged to the trail.
Enable federation on an event data store	You can federate an event data store to see the metadata associated with the event data store in the AWS Glue Data Catalog and run SQL queries on the event data using Amazon Athena. The table metadata stored in the AWS Glue Data Catalog lets the Athena query engine know how to find, read, and process the data that you want to query.
Stop or start event ingestion on an event data store	You can stop and start event ingestion on event data stores that collect CloudTrail management and data events, or AWS Config configuration items.
Create an integration with an event source outside of AWS	You can use CloudTrail Lake integrations to log and store user activity data from outside of AWS; from any source in your hybrid environments, such as in-house or SaaS applications hosted on-premises or in the cloud, virtual machines, or containers. For information about available integration partners, see AWS CloudTrail Lake Integrations.
View Lake sample queries in the CloudTrail console	The CloudTrail console provides a number of sample queries that can help you get started writing your own queries.
Create or edit a query	Queries in CloudTrail are authored in SQL. You can build a query on the CloudTrail Lake Editor tab by writing the query in SQL from scratch, or by opening a saved or sample query and editing it.
Save query results to an S3 bucket	When you run a query, you can save the query results to an S3 bucket.
Download saved query results	You can download a CSV file containing your saved CloudTrail Lake query results.
Validate saved query results	You can use CloudTrail query results integrity validation to determine whether the query results were modified, deleted, or unchanged after CloudTrail delivered the query results to the S3 bucket.

For more information about CloudTrail Lake, see Working with AWS CloudTrail Lake.

CloudTrail Lake event data stores and queries incur charges. When you create an event data store, you choose the pricing option you want to use for the event data store. The pricing option determines the cost for ingesting and storing events, and the default and maximum retention period for the event data store. When you run queries in Lake, you pay based upon the amount of data scanned. For information about CloudTrail pricing and managing Lake costs, see AWS CloudTrail Pricing and Managing CloudTrail Lake costs.

CloudTrail Lake dashboards

You can use CloudTrail Lake dashboards to see event trends for the event data stores in your account. CloudTrail Lake offers the following types of dashboards:

• Managed dashboards – You can view a managed dashboard to see event trends for an event data store that collects management events, data events, or Insights events. These dashboards are automatically available to you and are managed by CloudTrail Lake. CloudTrail offers 14 managed dashboards to choose from. You can manually refresh managed dashboards. You cannot modify, add, or remove the widgets for these dashboards, however, you can save a managed dashboard as a custom dashboard if you want to modify the widgets or set a refresh schedule.

• Custom dashboards – Custom dashboards allow you to query events in any event data store type. You can add up to 10 widgets to a custom dashboard. You can manually refresh a custom dashboard, or you can set a refresh schedule.

• Highlights dashboards – Enable the Highlights dashboard to view an at-a-glance overview of the AWS activity collected by the event data stores in your account. The Highlights dashboard is managed by CloudTrail and includes widgets that are relevant to your account. The widgets shown on the Highlights dashboard are unique to each account. These widgets could surface detected abnormal activity or anomalies. For example, your Highlights dashboard could include the Total cross-account access widget, which shows if there is an increase in abnormal cross-account activity. CloudTrail updates the Highlights dashboard every 6 hours. The dashboard shows the last 24 hours of data from the last update.

Each dashboard consists of one or more widgets and each widget represents a SQL query.

For more information, see CloudTrail Lake dashboards.

CloudTrail trails

A trail is a configuration that enables delivery of events to an Amazon S3 bucket that you specify. You can also deliver and analyze events in a trail with Amazon CloudWatch Logs and Amazon EventBridge.

Trails can log CloudTrail management events, data events, network activity events, and Insights events.

You can create both multi-Region and single-Region trails for your AWS account.

Multi-Region trails

When you create a multi-Region trail, CloudTrail records events in all AWS Regions that are enabled in your AWS account and delivers the CloudTrail event log files to an S3 bucket that you specify. As a best practice, we recommend creating a multi-Region trail because it captures activity in all enabled Regions. All trails created using the CloudTrail console are multi-Region trails. You can convert a single-Region trail to a multi-Region trail by using the AWS CLI. For more information, see Understanding multi-Region trails and opt-in Regions, Creating a trail with the console, and Converting a single-Region trail to a multi-Region trail.

Single-Region trails

When you create a single-Region trail, CloudTrail records the events in that Region only. It then delivers the CloudTrail event log files to an Amazon S3 bucket that you specify. You can only create a single-Region trail by using the AWS CLI. If you create additional single trails, you can have those trails deliver CloudTrail event log files to the same S3 bucket or to separate buckets. This is the default option when you create a trail using the AWS CLI or the CloudTrail API. For more information, see Creating, updating, and managing trails with the AWS CLI.

Note

For both types of trails, you can specify an Amazon S3 bucket from any Region.

If you have created an organization in AWS Organizations, you can create an organization trail that logs all events for all AWS accounts in that organization. Organization trails can apply to all AWS Regions, or the current Region. Organization trails must be created using the management account or delegated administrator account, and when specified as applying to an organization, are automatically applied to all member accounts in the organization. Member accounts can see the organization trail, but cannot modify or delete it. By default, member accounts do not have access to the log files for an organization trail in the Amazon S3 bucket.

By default, when you create a trail in the CloudTrail console, your event log files are encrypted with a KMS key. If you choose not to enable SSE-KMS encryption, your event logs are encrypted using Amazon S3 server-side encryption (SSE). You can store your log files in your bucket for as long as you want. You can also define Amazon S3 lifecycle rules to archive or delete log files automatically. If you want notifications about log file delivery and validation, you can set up Amazon SNS notifications.

CloudTrail publishes log files multiple times an hour, about every 5 minutes. These log files contain API calls from services in the account that support CloudTrail. For more information, see CloudTrail supported services and integrations.

Note

CloudTrail typically delivers logs within an average of about 5 minutes of an API call. This time is not guaranteed. Review the AWS CloudTrail Service Level Agreement for more information.

If you misconfigure your trail (for example, the S3 bucket is unreachable), CloudTrail will attempt to redeliver the log files to your S3 bucket for 30 days, and these attempted-to-deliver events will be subject to standard CloudTrail charges. To avoid charges on a misconfigured trail, you need to delete the trail.

CloudTrail captures actions made directly by the user or on behalf of the user by an AWS service. For example, an AWS CloudFormation CreateStack call can result in additional API calls to Amazon EC2, Amazon RDS, Amazon EBS, or other services as required by the AWS CloudFormation template. This behavior is normal and expected. You can identify if the action was taken by an AWS service with the invokedby field in the CloudTrail event.

The following table provides information about tasks you can perform on trails.

Task	Description
Logging management events	Configure your trails to log read-only, write-only, or all management events.
Log data events	You can use advanced event selectors to create fine-grained selectors to log only those data events of interest. For example, you can filter on the eventName field to include or exclude logging of specific API calls, which can help control costs. For more information, see Filtering data events by using advanced event selectors.
Log network activity events	Configure your trails to log network activity events. You can configure advanced event selectors to filter on the eventName, errorCode, and vpcEndpointId fields to log only those events of interest.
Log Insights events	Configure your trails to log Insights events to help you identify and respond to unusual activity associated with management API calls. 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 AWS CloudTrail Pricing.
View Insights events	After you enable CloudTrail Insights on a trail, you can view up to 90 days of Insights events by using the CloudTrail console or the AWS CLI.
Download Insights events	After you enable CloudTrail Insights on a trail, you can download a CSV or JSON file containing up to the past 90 days of Insights events for your trail.
Copy trail events to CloudTrail Lake	You can copy existing trail events to a CloudTrail Lake event data store to create a point-in-time snapshot of events logged to the trail.
Create and subscribe to an Amazon SNS topic	Subscribe to a topic to receive notifications about log file delivery to your bucket. Amazon SNS can notify you in multiple ways, including programmatically with Amazon Simple Queue Service. Note If you want to receive SNS notifications about log file deliveries from all Regions, specify only one SNS topic for your trail. If you want to programmatically process all events, see Using the CloudTrail Processing Library.
View your log files	Find and download your log files from the S3 bucket.
Monitor events with CloudWatch Logs	You can configure your trail to send events to CloudWatch Logs. You can then use CloudWatch Logs to monitor your account for specific API calls and events. Note If you configure a multi-Region trail to send events to a CloudWatch Logs log group, CloudTrail sends events from all Regions to a single log group.
Enable log encryption	Log file encryption provides an extra layer of security for your log files.
Enable log file integrity	Log file integrity validation helps you verify that log files have remained unchanged since CloudTrail delivered them.
Share log files with other AWS accounts	You can share log files between accounts.
Aggregate logs from multiple accounts	You can aggregate log files from multiple accounts to a single bucket.
Work with partner solutions	Analyze your CloudTrail output with a partner solution that integrates with CloudTrail. Partner solutions offer a broad set of capabilities, such as change tracking, troubleshooting, and security analysis.

You can deliver one copy of your ongoing management events to your S3 bucket at no charge from CloudTrail by creating a trail, however, there are Amazon S3 storage charges. For more information about CloudTrail pricing, see AWS CloudTrail Pricing. For information about Amazon S3 pricing, see Amazon S3 Pricing.

CloudTrail Insights events

AWS CloudTrail Insights help AWS users identify and respond to unusual activity associated with API call rates 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 rate are generated for write management APIs, and Insights events on API error rate are generated for both read and write management APIs.

By default, CloudTrail trails and event data stores don't log Insights events. You must configure your trail or event data store to log Insights events. For more information, see Logging Insights events with the CloudTrail console and Logging Insights events with the AWS CLI.

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 AWS CloudTrail Pricing.

Viewing Insights events for trails and event data stores

CloudTrail supports Insights events for both trails and event data stores, however, there are some differences in how you view and access Insights events.

Viewing Insights events for trails

If you have Insights events enabled on a trail, and CloudTrail detects unusual activity, Insights events are logged to a different folder or prefix in the destination S3 bucket for your trail. You can also see the type of insight and the incident time period when you view Insights events on the CloudTrail console. For more information, see Viewing Insights events for trails with the console.

After you enable CloudTrail Insights for the first time on a trail, CloudTrail may take up to 36 hours to begin delivering Insights events after you enable Insights events on a trail, provided that unusual activity is detected during that time.

Viewing Insights events for event data stores

To log Insights events in CloudTrail Lake, you need a destination event data store that logs Insights events and a source event data store that enables Insights and logs management events. For more information, see Create an event data store for Insights events with the console.

After you enable CloudTrail Insights for the first time on the source event data store, CloudTrail may take up to 7 days to begin delivering Insights events, provided that unusual activity is detected during that time.

If you have CloudTrail Insights enabled on a source event data store and CloudTrail detects unusual activity, CloudTrail delivers Insights events to your destination event data store. You can then query your destination event data store to get information about your Insights events and can optionally save the query results to an S3 bucket. For more information, see Create or edit a query with the CloudTrail console and View sample queries with the CloudTrail console.

You can view the Insights events dashboard to visualize the Insights events in your destination event data store. For more information about Lake dashboards, see CloudTrail Lake dashboards.

CloudTrail channels

CloudTrail supports two types of channels:

Channels for CloudTrail Lake integrations with event sources outside of AWS

CloudTrail Lake uses channels to bring events from outside of AWS into CloudTrail Lake from external partners that work with CloudTrail, or from your own sources. When you create a channel, you choose one or more event data stores to store events that arrive from the channel source. You can change the destination event data stores for a channel as needed, as long as the destination event data stores are set to log activity events. When you create a channel for events from an external partner, you provide a channel ARN to the partner or source application. The resource policy attached to the channel allows the source to transmit events through the channel. For more information, see Create an integration with an event source outside of AWS and CreateChannel in the AWS CloudTrail API Reference.

Service-linked channels

AWS services can create a service-linked channel to receive CloudTrail events on your behalf. The AWS service creating the service-linked channel configures advanced event selectors for the channel and specifies whether the channel applies to all Regions, or the current Region.

You can use the CloudTrail console or AWS CLI to view information about any CloudTrail service-linked channels created by AWS services.