How CloudTrail works - Amazon CloudTrail
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).

How CloudTrail works

CloudTrail is active in your Amazon account when you create it. When activity occurs in your Amazon account, that activity is recorded in a CloudTrail event. You can view the past 90 days of recorded API activity (management events) in an Amazon Web Services Region in the CloudTrail console by going to Event history.

For an ongoing record of events in your Amazon Web Services account, create a trail. Trails can log events for CloudTrail management, data, and Insights events.

To get started with CloudTrail, see Getting started with Amazon CloudTrail tutorials.

For CloudTrail pricing, see Amazon CloudTrail Pricing. For Amazon S3 and Amazon SNS pricing, see Amazon S3 Pricing and Amazon SNS Pricing.

Event history

The Event history provides a viewable, searchable, downloadable, and immutable record of the past 90 days of recorded management events in an Amazon Web Services Region. You can easily view 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 that exist in your account and is not affected by configuration changes you make to your trails.

CloudTrail trails

You can also create a CloudTrail trail to archive, analyze, and respond to changes in your Amazon resources. Trails can log CloudTrail management events, data events, and Insights events.

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. You can create trails with the CloudTrail console, the Amazon CLI, or the CloudTrail API.

You can create two types of trails for an Amazon account:

A trail that applies to all Regions

When you create a trail that applies to all Regions, CloudTrail records events in each Region and delivers the CloudTrail event log files to an S3 bucket that you specify. If a Region is added after you create a trail that applies to all Regions, that new Region is automatically included, and events in that Region are logged. Creating a multi-Region trail is a recommended best practice since you capture activity in all Regions in your account. All trails you create using the CloudTrail console are multi-Region. You can update a single-Region trail to log all Regions by using the Amazon CLI. For more information, see Creating a trail in the console and Converting a trail that applies to one Region to apply to all Regions.

A trail that applies to one Region

When you create a trail that applies to one Region, 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 Amazon CLI. If you create additional single trails, you can have those trails deliver CloudTrail event log files to the same Amazon S3 bucket or to separate buckets. This is the default option when you create a trail using the Amazon CLI or the CloudTrail API. For more information, see Creating, updating, and managing trails with the Amazon Command Line Interface.

Note

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

Beginning on April 12, 2019, trails are viewable only in the Amazon Regions where they log events. If you create a trail that logs events in all Amazon Regions, it will appear in the console in all Amazon Regions. If you create a trail that only logs events in a single Amazon Region, you can view and manage it only in that Amazon Region.

If you have created an organization in Amazon Organizations, you can create an organization trail that logs all events for all Amazon accounts in that organization. Organization trails can apply to all Amazon 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.

You can change the configuration of a trail after you create it, including whether it logs events in one Region or all Regions. To change a single-Region trail to an all-Region trail, or vice-versa, you must run the Amazon CLI update-trail command. You can also change whether it logs data or CloudTrail Insights events. Changing whether a trail logs events in one Region or in all Regions affects which events are logged. For more information, see Managing trails with the Amazon CLI (Amazon CLI), and Working with CloudTrail log files.

By default, CloudTrail event log files from trails are encrypted using Amazon S3 server-side encryption (SSE). You can also choose to encrypt your log files with an Amazon Key Management Service (Amazon KMS) key. 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.

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 Amazon service. For example, an Amazon CloudFormation CreateStack call can result in additional API calls to Amazon EC2, Amazon RDS, Amazon EBS, or other services as required by the Amazon CloudFormation template. This behavior is normal and expected. You can identify if the action was taken by an Amazon service with the invokedby field in the CloudTrail event.

CloudTrail channels

CloudTrail supports service-linked channels.

Service-linked channels

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

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