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 objects, 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.

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, click the pencil icon or Configure.

  3. Type the bucket name and prefix (optional). For each trail, you can add up to 250 S3 objects.

    1. To log data events for all S3 objects in a bucket, specify an S3 bucket and an empty prefix. When an event occurs on an object in that S3 bucket, the trail processes and logs the event. For more information, see Example: Logging data events for all S3 objects.

    2. To log data events for specific S3 objects, specify an S3 bucket and the object prefix. When an event occurs on an object in that S3 bucket and the object starts with the specified prefix, the trail processes and logs the event. For more information, see Example: Logging data events for specific S3 objects.

    3. You can also specify S3 objects that belong to other AWS accounts. For more information, see Logging Data Events for S3 Objects in other AWS Accounts.

  4. For each resource, specify whether you want to log Read-only, Write-only, or All events.

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

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

  7. Choose Save.

Examples: Logging Data Events for Amazon S3 Objects

Logging data events for all S3 objects

The following example shows how to configure your trail to log data events for all objects in an S3 bucket.

  1. For your trail, you specify an S3 bucket named bucket-1, an empty prefix, and that you want all events.

  2. You upload an object to bucket-1.

  3. The PutObject API operation is a data event. Because you 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.

  4. You upload another object to bucket-2.

  5. The PutObject API operation occurred on an object in an S3 bucket that you didn't specify for the trail. The trail doesn't log the event.

Logging data events for specific S3 objects

The following example shows how you can configure a trail to log events for specific S3 objects.

  1. For your trail, you specify an S3 bucket named bucket-3, with the prefix my-images, and that you want write-only events.

  2. You delete an object that begins with the my-images prefix in the bucket, such as arn:aws:s3:::bucket-3/my-images/example.jpg.

  3. The DeleteObject API operation is a write-only data event. The event occurred on an object that matches the S3 bucket and prefix that you specified in the trail. The trail processes and logs the event.

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

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

  6. You call the GetObject API operation for the object, arn:aws:s3:::bucket-3/my-images/example.jpg.

  7. The event occurred on a bucket and prefix that you specified in your trail, but GetObject is a read-only event. 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 configure up to five event selectors and up to 250 S3 objects for a trail.

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.