Menu
AWS CloudTrail
User Guide (Version 1.0)

Logging Data and Management Events for Trails

When an event occurs in your account, CloudTrail evaluates whether the event matches the settings for your trails. Only events that match your trail settings are delivered to your Amazon S3 bucket and Amazon CloudWatch Logs log group.

You can configure your trails to log the following:

  • CloudTrail supports logging Amazon S3 object-level API operations such as GetObject, DeleteObject, and PutObject. These events are called Data Events.

  • All other events that CloudTrail logs are called Management Events.

You can configure multiple trails differently so that the trails process and log only the events that you specify. For example, one trail can log read-only data and management events, so that all read-only events are delivered to one S3 bucket. Another trail can log only write-only data and management events, so that all write-only events are delivered to a separate S3 bucket.

You can also configure your trails to have one trail log and deliver all management events to one S3 bucket, and configure another trail to log and deliver all data events to another S3 bucket.

By default, trails log all management events and don't include data events. Additional charges apply for data events. For more information, see AWS CloudTrail Pricing.

Note

The events that are logged by your trails are available in Amazon CloudWatch Events. For example, if you configure a trail to log data events for S3 objects but not management events, your trail processes and logs only data events for the specified S3 objects. The data events for these S3 objects are available in Amazon CloudWatch Events. For more information, see AWS API Call Events in the Amazon CloudWatch Events User Guide.

Data Events

Data events are object-level API operations that access Amazon S3 buckets, such as GetObject, DeleteObject, and PutObject. By default, trails don't log data events, but you can configure trails to log data events for S3 objects that you specify, or to log data events for all Amazon S3 buckets in your AWS account.

For a list of supported data events that CloudTrail logs for Amazon S3 objects, see Amazon S3 Object-Level Actions Tracked by CloudTrail Logging in the Amazon Simple Storage Service Developer Guide.

Logging Data Events with the AWS Management Console

  1. Navigate to the Trails page of the CloudTrail console and choose the trail.

  2. For Data events, choose the pencil icon or Configure.

    1. To configure data event logging for all Amazon S3 buckets in your AWS account, select Select all S3 buckets in your account, and then choose whether you want to log Read events, such as GetObject; Write events, such as PutObject; or both types of events. This setting takes precedence over any settings you configure for individual buckets. For example, if you specify logging Read events for all S3 buckets, and then choose to add a specific bucket for data event logging, Read will already be selected for that bucket. You cannot clear the selection. You can only configure the option for Write.

      Note

      If you select or clear an option for all buckets, that change is applied to all buckets you might have individually configured for data event logging. Consider reviewing the data event settings for individual buckets after you make changes to the data event settings for all buckets.

    2. To configure data event logging for individual Amazon S3 buckets, choose Add S3 bucket. Type the bucket name and prefix (optional). For each trail, you can add up to 250 S3 bucket/prefix combinations. Note that this restriction does not apply if you configure data event logging for all Amazon S3 buckets.

    3. For each resource, specify whether you want to log Read, Write, or both types of events.

    4. You can edit the bucket name, prefix, Read/Write option, or remove the resource by choosing the x icon.

      Note

      If you have configured data event logging for all S3 buckets in your AWS account, the settings you configured take precedence over individual bucket settings. In this case, you cannot edit an option that is set for all buckets.

    5. To filter resources that you added, type the bucket name or prefix in the search field.

  3. Choose Save.

Examples: Logging Data Events for Amazon S3 Objects

Logging data events for all S3 objects in an S3 bucket

The following example demonstrates how logging works when you configure logging of all data events for an S3 bucket named bucket-1. In this example, the CloudTrail user specified an empty prefix, and the option to log both Read and Write data events.

  1. A user uploads an object to bucket-1.

  2. The PutObject API operation is an Amazon S3 object-level API. It is recorded as a data event in CloudTrail. Because the CloudTrail user specified an S3 bucket with an empty prefix, events that occur on any object in that bucket are logged. The trail processes and logs the event.

  3. Another user uploads an object to bucket-2.

  4. The PutObject API operation occurred on an object in an S3 bucket that wasn't specified for the trail. The trail doesn't log the event.

Logging data events for specific S3 objects

The following example demonstrates how logging works when you configure a trail to log events for specific S3 objects. In this example, the CloudTrail user specified an S3 bucket named bucket-3, with the prefix my-images, and the option to log only Write data events.

  1. A user deletes an object that begins with the my-images prefix in the bucket, such as arn:aws:s3:::bucket-3/my-images/example.jpg.

  2. The DeleteObject API operation is an Amazon S3 object-level API. It is recorded as a Write data event in CloudTrail.. The event occurred on an object that matches the S3 bucket and prefix specified in the trail. The trail processes and logs the event.

  3. Another user deletes an object with a different prefix in the S3 bucket, such as arn:aws:s3:::bucket-3/my-videos/example.avi.

  4. The event occurred on an object that doesn't match the prefix specified in your trail. The trail doesn't log the event.

  5. A user calls the GetObject API operation for the object, arn:aws:s3:::bucket-3/my-images/example.jpg.

  6. The event occurred on a bucket and prefix that are specified in the trail, but GetObject is a read-type Amazon S3 object-level API. It is recorded as a Read data event in CloudTrail, and the trail is not configured to log Read events. The trail doesn't log the event.

Note

We recommend you do not use the same S3 bucket to receive log files that you have specified in the data events section. Using the same S3 bucket causes your trail to log a data event each time log files are delivered to your S3 bucket. For example, when the trail delivers logs, the PutObject event occurs on the S3 bucket. If the S3 bucket is also specified in the data events section, the trail processes and logs the PutObject event as a data event. That action is another PutObject event, and the trail processes and logs the event again.

Logging Data Events for S3 Objects in other AWS Accounts

When you configure your trail to log data events, you can also specify S3 objects that belong to other AWS accounts. When an event occurs on a specified object, CloudTrail evaluates whether the event matches any trails in each account. If the event matches the settings for a trail, the trail processes and logs the event for that account.

If you own an S3 object and you specify it in your trail, your trail logs events that occur on the object in your account. Because you own the object, your trail also logs events when other accounts call the object.

If you specify an S3 object in your trail, and another account owns the object, your trail only logs events that occur on that object in your account. Your trail doesn't log events that occur in other accounts.

Example: Logging data events for an S3 object for two AWS accounts

The following example shows how two AWS accounts configure CloudTrail to log events for the same S3 object.

  1. In your account, you want your trail to log data events for all objects in your S3 bucket named owner-bucket. You configure the trail by specifying the S3 bucket with an empty object prefix.

  2. Bob has a separate account that has been granted access to the S3 bucket. Bob also wants to log data events for all objects in the same S3 bucket. For his trail, he configures his trail and specifies the same S3 bucket with an empty object prefix.

  3. Bob uploads an object to the S3 bucket with the PutObject API operation.

  4. This event occurred in his account and it matches the settings for his trail. Bob's trail processes and logs the event.

  5. Because you own the S3 bucket and the event matches the settings for your trail, your trail also processes and logs the same event.

  6. You upload an object to the S3 bucket.

  7. This event occurs in your account and it matches the settings for your trail. Your trail processes and logs the event.

  8. Because the event didn't occur in Bob's account, and he doesn't own the S3 bucket, Bob's trail doesn't log the event.

Management Events

By default, trails are configured to log management events. All events that are not data events are management events. Example management events include the EC2 RunInstances, DescribeInstances, and TerminateInstances API operations. Management events can also include non-API events that occur in your account. For example, when a user logs in to your account, CloudTrail logs the ConsoleLogin event. For more information, see Non-API Events Captured by CloudTrail.

For a list of supported management events that CloudTrail logs for AWS services, see CloudTrail Topics by AWS Service.

Note

The CloudTrail Event history feature supports only management events. For more information, see Viewing Events with CloudTrail Event History.

Logging Management Events with the AWS Management Console

  1. Navigate to the Trails page of the CloudTrail console and choose the trail.

  2. For Management events, click the pencil icon.

  3. For Read/Write events, choose if you want your trail to log All, Read-only, Write-only, or None, and then choose Save.

Read-only and Write-only Events

When you configure your trail to log data and management events, you can specify whether you want read-only events, write-only events, or both.

  • Read-only

    Read-only events include API operations that read your resources, but don't make changes. For example, read-only events include the Amazon EC2 DescribeSecurityGroups and DescribeSubnets API operations. These operations return only information about your Amazon EC2 resources and don't change your configurations.

  • Write-only

    Write-only events include API operations that modify (or might modify) your resources. For example, the Amazon EC2 RunInstances and TerminateInstances API operations modify your instances.

  • All

    Your trail logs both.

Example: Logging read-only and write-only events for separate trails

The following example shows how you can configure trails to split log activity for an account into separate S3 buckets: one bucket receives read-only events and a second bucket receives write-only events.

  1. You create a trail and choose an S3 bucket named read-only-bucket to receive log files. You then update the trail to specify that you want read-only management events and data events.

  2. You create a second trail and choose an S3 bucket named write-only-bucket to receive log files. You then update the trail to specify that you want write-only management events and data events.

  3. The Amazon EC2 DescribeInstances and TerminateInstances API operations occur in your account.

  4. The DescribeInstances API operation is a read-only event and it matches the settings for the first trail. The trail logs and delivers the event to the read-only-bucket.

  5. The TerminateInstances API operation is a write-only event and it matches the settings for the second trail. The trail logs and delivers the event to the write-only-bucket.

Logging Events with the AWS Command Line Interface

You can configure your trails to log management and data events using the AWS CLI.

To view whether your trail is logging management and data events, run the get-event-selectors command.

Copy
aws cloudtrail get-event-selectors --trail-name TrailName

The following example returns the default settings for a trail. By default, trails log all management events and don't log data events.

Copy
{ "EventSelectors": [ { "IncludeManagementEvents": true, "DataResources": [], "ReadWriteType": "All" } ], "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName" }

To configure your trail to log management and data events, run the put-event-selectors command. The following example shows how to configure your trail to include all management and data events for two S3 objects. You can specify from 1 to 5 event selectors for a trail. You can specify from 1 to 250 data resources for a trail.

Note

The maximum number of S3 data resources is 250, regardless of the number of event selectors.

Copy
aws cloudtrail put-event-selectors --trail-name TrailName --event-selectors '[{ "ReadWriteType": "All", "IncludeManagementEvents":true, "DataResources": [{ "Type": "AWS::S3::Object", "Values": ["arn:aws:s3:::mybucket/prefix", "arn:aws:s3:::mybucket2/prefix2"] }] }]'

The following example returns the event selector configured for the trail.

Copy
{ "EventSelectors": [ { "IncludeManagementEvents": true, "DataResources": [ { "Values": [ "arn:aws:s3:::mybucket/prefix", "arn:aws:s3:::mybucket2/prefix2", ], "Type": "AWS::S3::Object" } ], "ReadWriteType": "All" } ], "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName" }

Logging Events with the AWS SDKs

Use the GetEventSelectors operation to see whether your trail is logging management and data events for a trail. You can configure your trails to log management and data events with the PutEventSelectors operation. For more information, see the AWS CloudTrail API Reference.

Sending Events to Amazon CloudWatch Logs

CloudTrail supports sending data and management events to CloudWatch Logs. When you configure your trail to send events to your CloudWatch Logs log group, CloudTrail sends only the events that you specify in your trail. For example, if you configure your trail to log data events only, your trail delivers data events only to your CloudWatch Logs log group. For more information, see Monitoring CloudTrail Log Files with Amazon CloudWatch Logs.