CloudTrail concepts - Amazon CloudTrail
What are CloudTrail events?What is CloudTrail event history?What are trails?What are organization trails?How do you manage CloudTrail?How do you control access to CloudTrail?How do you log management and data events?How do you log CloudTrail Insights events?How do you perform monitoring with CloudTrail?How does CloudTrail behave regionally and globally?Global service events How does CloudTrail relate to other Amazon monitoring services?Partner solutions
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).

CloudTrail concepts

This section summarizes basic concepts related to CloudTrail.

What are CloudTrail events?

An event in CloudTrail is the record of an activity in an Amazon account. This activity can be an action taken by an IAM identity, or service that is monitorable by CloudTrail. CloudTrail events provide a history of both API and non-API account activity made through the Amazon Web Services Management Console, Amazon SDKs, command line tools, and other Amazon services. There are three types of events that can be logged in CloudTrail: management events, data events, and CloudTrail Insights events. By default, trails log management events, but not data or Insights events.

All event types use a CloudTrail JSON log format.

Note

CloudTrail does not log all Amazon services and all events. For more information about which APIs are logged for a specific service, see documentation for that service in CloudTrail supported services and integrations.

What are management events?

Management events provide information about management operations that are performed on resources in your Amazon account. These are also known as control plane operations. Example management events include:

  • Configuring security (for example, Amazon Identity and Access Management AttachRolePolicy API operations).

  • Registering devices (for example, Amazon EC2 CreateDefaultVpc API operations).

  • Configuring rules for routing data (for example, Amazon EC2 CreateSubnet API operations).

  • Setting up logging (for example, Amazon CloudTrail CreateTrail API operations).

Management events can also include non-API events that occur in your account. For example, when a user signs in to your account, CloudTrail logs the ConsoleLogin event. For more information, see Non-API events captured by CloudTrail. For a list of management events that CloudTrail logs for Amazon services, see CloudTrail supported services and integrations.

What are data events?

Data events provide information about the resource operations performed on or in a resource. These are also known as data plane operations. Data events are often high-volume activities.

The following table shows the data event types available for trails. The Data event type (console) column shows the appropriate selection in the console. The resources.Type column shows the resources.Type value that you would specify to include data events of that type in your trail.

For trails, you can use basic or advanced event selectors to log data events for Amazon S3 buckets and bucket objects, Lambda functions, and DynamoDB tables (shown in the first three rows of the table). You can use only advanced event selectors to log the data event types shown in the remaining rows.

Amazon service Description Data event type (console) resources.Type
Amazon DynamoDB

Amazon DynamoDB object-level API activity on tables (for example, PutItem, DeleteItem, and UpdateItem API operations). For more information about DynamoDB events, see DynamoDB data plane events in CloudTrail.

 DynamoDB AWS::DynamoDB::Table
Amazon Lambda

Amazon Lambda function execution activity (the Invoke API).

 Lambda AWS::Lambda::Function
Amazon S3

Amazon S3 object-level API activity (for example, GetObject, DeleteObject, and PutObject API operations) on buckets and objects in buckets.

 S3 AWS::S3::Object
Amazon CloudTrail

CloudTrail PutAuditEvents activity on a CloudTrail Lake channel that is used to log events from outside Amazon.

 CloudTrail AWS::CloudTrail::Channel
Amazon CodeWhisperer Amazon CodeWhisperer API activity on a profile. CodeWhisperer AWS::CodeWhisperer::Profile
Amazon Cognito

Amazon Cognito API activity on Amazon Cognito identity pools.

 Cognito Identity Pools AWS::Cognito::IdentityPool
Amazon DynamoDB

Amazon DynamoDB API activity on streams.

 DynamoDB Streams AWS::DynamoDB::Stream
Amazon Elastic Block Store

Amazon Elastic Block Store (EBS) direct APIs, such as PutSnapshotBlock, GetSnapshotBlock, and ListChangedBlocks on Amazon EBS snapshots.

 Amazon EBS direct APIs AWS::EC2::Snapshot
Amazon EMR Amazon EMR API activity on a write-ahead log workspace. EMR write-ahead log workspace AWS::EMRWAL::Workspace
Amazon FinSpace

Amazon FinSpace API activity on environments.

 FinSpace AWS::FinSpace::Environment
Amazon Glue

Amazon Glue API activity on tables that were created by Lake Formation.

Note

Amazon Glue data events for tables are currently supported only in the following regions:

  • US East (N. Virginia)

  • US East (Ohio)

  • US West (Oregon)

  • Europe (Ireland)

  • Asia Pacific (Tokyo) Region

 Lake Formation AWS::Glue::Table
Amazon GuardDuty

Amazon GuardDuty API activity for a detector.

 GuardDuty detector AWS::GuardDuty::Detector
Amazon Kendra Intelligent Ranking

Amazon Kendra Intelligent Ranking API activity on rescore execution plans.

 Kendra Ranking AWS::KendraRanking::ExecutionPlan
Amazon Managed Blockchain

Amazon Managed Blockchain JSON-RPC calls on Ethereum nodes, such as eth_getBalance or eth_getBlockByNumber.

 Managed Blockchain AWS::ManagedBlockchain::Node
Amazon SageMaker

Amazon SageMaker API activity on feature stores.

 SageMaker feature store AWS::SageMaker::FeatureGroup
Amazon SageMaker

Amazon SageMaker API activity on experiment trial components.

 SageMaker metrics experiment trial component AWS::SageMaker::ExperimentTrialComponent
Amazon S3

Amazon S3 API activity on access points.

 S3 Access Point AWS::S3::AccessPoint
Amazon S3

Amazon S3 Object Lambda access points API activity, such as calls to CompleteMultipartUpload and GetObject.

 S3 Object Lambda AWS::S3ObjectLambda::AccessPoint
Amazon S3 on Outposts

Amazon S3 on Outposts object-level API activity.

 S3 Outposts AWS::S3Outposts::Object

Data events are not logged by default when you create a trail. To record CloudTrail data events, you must explicitly add the supported resources or resource types for which you want to collect activity. For more information, see Creating a trail.

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

What are Insights events?

CloudTrail Insights events capture unusual API call rate or error rate activity in your Amazon account by analyzing CloudTrail management activity. If you have Insights events enabled, 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. Insights events provide relevant information, such as the associated API, error code, incident time, and statistics, that help you understand and act on unusual activity. Unlike other types of events captured in a CloudTrail trail, Insights events are logged only when CloudTrail detects changes in your account's API usage or error rate logging that differ significantly from the account's typical usage patterns. Examples of activity that might generate Insights events include:

  • Your account typically logs no more than 20 Amazon S3 deleteBucket API calls per minute, but your account starts to log an average of 100 deleteBucket API calls per minute. An Insights event is logged at the start of the unusual activity, and another Insights event is logged to mark the end of the unusual activity.

  • Your account typically logs 20 calls per minute to the Amazon EC2 AuthorizeSecurityGroupIngress API, but your account starts to log zero calls to AuthorizeSecurityGroupIngress. An Insights event is logged at the start of the unusual activity, and ten minutes later, when the unusual activity ends, another Insights event is logged to mark the end of the unusual activity.

  • Your account typically logs less than one AccessDeniedException error in a seven-day period on the Amazon Identity and Access Management API, DeleteInstanceProfile. Your account starts to log an average of 12 AccessDeniedException errors per minute on the DeleteInstanceProfile API call. An Insights event is logged at the start of the unusual error rate activity, and another Insights event is logged to mark the end of the unusual activity.

These examples are provided for illustration purposes only. Your results may vary depending on your use case.

Insights events are disabled by default when you create a trail. To log CloudTrail Insights events, you must explicitly enable Insights event collection on a new or existing trail, and the trail must log CloudTrail management events. For more information, see Creating a trail and Logging Insights events for trails.

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

What is CloudTrail event history?

CloudTrail event history provides a viewable, searchable, downloadable, and immutable record of the past 90 days of CloudTrail management events in an Amazon Web Services Region. You can use this history to gain visibility into actions taken in your Amazon account in the Amazon Web Services Management Console, Amazon SDKs, command line tools, and other Amazon services. You can customize your view of event history in the CloudTrail console by selecting which columns are displayed. For more information, see Viewing events with CloudTrail Event history.

What are trails?

A trail is a configuration that enables delivery of CloudTrail events to an Amazon S3 bucket, CloudWatch Logs, and Amazon EventBridge. You can use a trail to filter the CloudTrail events you want delivered, encrypt your CloudTrail event log files with an Amazon KMS key, and set up Amazon SNS notifications for log file delivery. For more information about how to create and manage a trail, see Creating a trail for your Amazon Web Services account.

What are organization trails?

An organization trail is a configuration that enables delivery of CloudTrail events in the management account, delegated administrator account, and all member accounts in an Amazon Organizations organization to the same Amazon S3 bucket, CloudWatch Logs, and Amazon EventBridge. Creating an organization trail helps you define a uniform event logging strategy for your organization.

When you create an organization trail, a trail with the name that you give it will be created in every Amazon account that belongs to your organization. Users with CloudTrail permissions in member accounts will be able to see this trail (including the trail ARN) when they log into the Amazon CloudTrail console from their Amazon accounts, or when they run Amazon CLI commands such as describe-trails (although member accounts must use the ARN for the organization trail, and not the name, when using the Amazon CLI). However, users in member accounts will not have sufficient permissions to delete the organization trail, turn logging on or off, change what types of events are logged, or otherwise alter the organization trail in any way. For more information about Amazon Organizations, see Organizations Terminology and Concepts. For more information about creating and working with organization trails, see Creating a trail for an organization.

How do you manage CloudTrail?

CloudTrail console

You can use and manage the service with the Amazon CloudTrail console. The console provides a user interface for performing many CloudTrail tasks such as:

  • Viewing recent events and event history for your Amazon account.

  • Downloading a filtered or complete file of the last 90 days of events.

  • Creating and editing CloudTrail trails.

  • Configuring CloudTrail trails, including:

    • Selecting an Amazon S3 bucket for trails.

    • Setting a prefix.

    • Configuring delivery to CloudWatch Logs.

    • Using Amazon KMS keys for encryption of trail data.

    • Enabling Amazon SNS notifications for log file delivery on trails.

    • Adding and managing tags for your trails.

Beginning on April 12, 2019, trails will be 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.

For more information about the Amazon Web Services Management Console, see Amazon Web Services Management Console.

CloudTrail CLI

The Amazon Command Line Interface is a unified tool that you can use to interact with CloudTrail from the command line. For more information, see the Amazon Command Line Interface User Guide. For a complete list of CloudTrail CLI commands, see Available Commands.

CloudTrail APIs

In addition to the console and the CLI, you can also use the CloudTrail RESTful APIs to program CloudTrail directly. For more information, see the Amazon CloudTrail API Reference.

Amazon SDKs

As an alternative to using the CloudTrail API, you can use one of the Amazon SDKs. Each SDK consists of libraries and sample code for various programming languages and platforms. The SDKs provide a convenient way to create programmatic access to CloudTrail. For example, you can use the SDKs to sign requests cryptographically, manage errors, and retry requests automatically. For more information, see the Tools for Amazon Web Services page.

Why use tags for trails?

A tag is a customer-defined key and optional value that can be assigned to Amazon resources, such as CloudTrail trails, Amazon S3 buckets used to store CloudTrail log files, Amazon Organizations organizations and organizational units, and many more. By adding the same tags to trails and to the Amazon S3 buckets you use to store log files for trails, you can make it easier to manage, search for, and filter these resources with Amazon Resource Groups. You can implement tagging strategies to help you consistently, effectively, and easily find and manage your resources. For more information, see Amazon Tagging Strategies.

How do you control access to CloudTrail?

Amazon Identity and Access Management is a web service that enables Amazon Web Services (Amazon) customers to securely control access to Amazon resources. Using IAM, you can centrally manage permissions that control which CloudTrail resources users can access. For more information about controlling user permissions, see Controlling user permissions for CloudTrail.

How do you log management and data events?

By default, trails log management events for your Amazon account and don't include data events. You can choose to create or update trails to log data events. Only events that match your trail settings are delivered to your Amazon S3 bucket, and optionally to an Amazon CloudWatch Logs log group. If the event doesn't match the settings for a trail, the trail doesn't log the event. For more information, see Working with CloudTrail log files.

How do you log CloudTrail Insights events?

Amazon CloudTrail Insights helps Amazon users identify and respond to unusual volumes of API calls or errors logged on API calls by continuously analyzing CloudTrail management events. An Insights event is a record of unusual levels of write management API activity, or unusual levels of errors returned on management API activity. The details page of an Insights event shows the event as a graph of unusual activity, and shows the start and end times of the unusual activity, along with the baseline that is used to determine whether the activity is unusual. By default, trails don't log CloudTrail Insights events. In the console, you can choose to log Insights events when you create or update a trail. When you use the CloudTrail API, you can log Insights events by editing the settings of an existing trail with the PutInsightSelectors API. Additional charges apply for logging CloudTrail Insights events. For more information, see Logging Insights events for trails and Amazon CloudTrail Pricing.

How do you perform monitoring with CloudTrail?

CloudWatch Logs, EventBridge, and CloudTrail

Amazon CloudWatch is a web service that collects and tracks metrics to monitor your Amazon Web Services (Amazon) resources and the applications that you run on Amazon. Amazon CloudWatch Logs is a feature of CloudWatch that you can use specifically to monitor log data. Integration with CloudWatch Logs enables CloudTrail to send events containing API activity in your Amazon account to a CloudWatch Logs log group. CloudTrail events that are sent to CloudWatch Logs can trigger alarms according to the metric filters you define. You can optionally configure CloudWatch alarms to send notifications or make changes to the resources that you are monitoring based on log stream events that your metric filters extract. Using CloudWatch Logs, you can also track CloudTrail events alongside events from the operating system, applications, or other Amazon services that are sent to CloudWatch Logs. For more information, see Monitoring CloudTrail Log Files with Amazon CloudWatch Logs.

Amazon EventBridge is an Amazon service that delivers a near real-time stream of system events that describe changes in Amazon resources. In EventBridge, you can create rules that respond to events recorded by CloudTrail. For more information, see Create a rule in Amazon EventBridge.

You can deliver events that you are subscribed to on your trail to EventBridge. When you create a rule with the EventBridge console, choose either the Amazon API Call via CloudTrail detail-type to deliver CloudTrail data and management events, or the Amazon Insight via CloudTrail detail-type to deliver Insights events.

To record events with a detail-type value of Amazon API Call via CloudTrail, you must have an active trail that is logging management or data events. For more information about how to create a trail, see Creating a trail.

To record events with a detail-type value of Amazon Insight via CloudTrail, you must have an active trail that is logging Insights events. For information about logging Insights events, see Logging Insights events for trails.

How does CloudTrail behave regionally and globally?

A trail can be applied to all Regions or a single Region. As a best practice, create a trail that applies to all Regions in the Amazon partition in which you are working. This is the default setting when you create a trail in the CloudTrail console.

Note

Turning on a trail means that you create a trail and start delivery of CloudTrail event log files to an Amazon S3 bucket. In the CloudTrail console, logging is turned on automatically when you create a trail.

What are the advantages of applying a trail to all Regions?

A trail that applies to all Amazon Regions has the following advantages:

  • The configuration settings for the trail apply consistently across all Amazon Regions.

  • You receive CloudTrail events from all Amazon Regions in a single Amazon S3 bucket and, optionally, in a CloudWatch Logs log group.

  • You manage trail configuration for all Amazon Regions from one location.

  • You immediately receive events from a new Amazon Region. When a new Amazon Region is launched, CloudTrail automatically creates a copy of all of your Region trails for you in the new Region with the same settings as your original trail.

  • You don't need to create trails in Amazon Regions that you don't use often in order to monitor for unusual activity. Any activity in any Amazon Region is logged in a trail that applies to all Amazon Regions.

What happens when you apply a trail to all Regions?

When you apply a trail to all Amazon Regions, CloudTrail uses the trail that you create in a particular Region to create trails with identical configurations in all other Regions in your account.

This has the following effects:

  • CloudTrail delivers log files for account activity from all Amazon Regions to the single Amazon S3 bucket that you specify, and, optionally, to a CloudWatch Logs log group.

  • If you configured an Amazon SNS topic for the trail, SNS notifications about log file deliveries in all Amazon Regions are sent to that single SNS topic.

  • If you enabled it, log file integrity validation is enabled for the trail in all Amazon Regions. For information, see Validating CloudTrail log file integrity.

Regardless of whether a trail is multi-Region or single-Region, events sent to Amazon EventBridge are received in each Region's event bus, rather than in one single event bus.

Multiple trails per Region

If you have different but related user groups, such as developers, security personnel, and IT auditors, you can create multiple trails per Region. This allows each group to receive its own copy of the log files.

CloudTrail supports five trails per Region. A trail that applies to all Amazon Regions counts as one trail in every Region.

The following example is a Region with five trails:

  • You create two trails in the US West (N. California) Region that apply to this Region only.

  • You create two more trails in US West (N. California) Region that apply to all Amazon Regions.

  • You create a trail in the Asia Pacific (Sydney) Region that applies to all Amazon Regions. This trail also exists as a trail in the US West (N. California) Region.

Trails appear in the Amazon Region where they exist. Trails that log events in all Amazon Regions appear in every Region. You can view a list of trails in an Amazon Region in the Trails page of the CloudTrail console. For more information, see Updating a trail. For CloudTrail pricing, see Amazon CloudTrail Pricing.

Amazon Security Token Service and CloudTrail

Amazon Security Token Service (Amazon STS) is a service that has a global endpoint and also supports Region-specific endpoints. An endpoint is a URL that is the entry point for web service requests. For example, https://cloudtrail.us-west-2.amazonaws.com is the US West (Oregon) regional entry point for the Amazon CloudTrail service. Regional endpoints help reduce latency in your applications.

When you use an Amazon STS Region-specific endpoint, the trail in that Region delivers only the Amazon STS events that occur in that Region. For example, if you are using the endpoint sts.us-west-2.amazonaws.com, the trail in us-west-2 delivers only the Amazon STS events that originate from us-west-2. For more information about Amazon STS regional endpoints, see Activating and Deactivating Amazon STS in an Amazon Region in the IAM User Guide.

For a complete list of Amazon regional endpoints, see Amazon Regions and Endpoints in the Amazon Web Services General Reference. For details about events from the global Amazon STS endpoint, see Global service events.

Global service events

Important

As of November 22, 2021, Amazon CloudTrail will make Amazon CloudFront events available only in the Region where the event was processed, the China (Ningxia) Region, cn-northwest-1. For trails monitoring global service events, be sure to convert single-Region trails in China (Beijing) Region, cn-north-1, to multi-Region trails, to include events from China (Ningxia) Region, cn-northwest-1. When referencing CloudFront events, also remember to update the Region of your lookup-events API calls referencing China (Beijing) Region, cn-north-1, to China (Ningxia) Region, cn-northwest-1. For more information about using the CLI to update or create trails for global service events and to update lookup events, see Viewing CloudTrail events with the Amazon CLI and Using update-trail.

For most services, events are recorded in the Region where the action occurred. For global services such as Amazon Identity and Access Management (IAM), Amazon STS, and Amazon CloudFront, events are delivered to any trail that includes global services.

For most global services, events are logged as occurring in the China (Beijing) Region, but some global service events are logged as occurring in the China (Ningxia) Region.

To avoid receiving duplicate global service events, remember the following:

  • Global service events are delivered by default to trails that are created using the CloudTrail console. Events are delivered to the bucket for the trail.

  • If you have multiple single Region trails, consider configuring your trails so that global service events are delivered in only one of the trails. For more information, see Enabling and disabling global service event logging.

  • If you change the configuration of a trail from logging all Regions to logging a single Region, global service event logging is turned off automatically for that trail. Similarly, if you change the configuration of a trail from logging a single Region to logging all Regions, global service event logging is turned on automatically for that trail.

    For more information about changing global service event logging for a trail, see Enabling and disabling global service event logging.

Example:

  1. You create a trail in the CloudTrail console. By default, this trail logs global service events.

  2. You have multiple single Region trails.

  3. You do not need to include global services for the single Region trails. Global service events are delivered for the first trail. For more information, see Creating, updating, and managing trails with the Amazon Command Line Interface.

Note

When you create or update a trail with the Amazon CLI, Amazon SDKs, or CloudTrail API, you can specify whether to include or exclude global service events for trails. You cannot configure global service event logging from the CloudTrail console.

How does CloudTrail relate to other Amazon monitoring services?

CloudTrail adds another dimension to the monitoring capabilities already offered by Amazon. It does not change or replace logging features you might already be using, such as those for Amazon S3 or Amazon CloudFront subscriptions. Amazon CloudWatch focuses on performance monitoring and system health. CloudTrail focuses on API activity. Although CloudTrail does not report on system performance or health, you can use CloudTrail with CloudWatch alarms to notify you about activity that you might be interested in.

Partner solutions

Amazon partners with third-party specialists in logging and analysis to provide solutions that use CloudTrail output. For more information, visit the CloudTrail detail page at Amazon CloudTrail.