Logging Data Events for Trails - AWS CloudTrail

Logging Data Events for Trails

By default, trails do not log 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 provide visibility into the resource operations performed on or within a resource. These are also known as data plane operations. Data events are often high-volume activities.

The following two data types are recorded:

  • Amazon S3 object-level API activity (for example, GetObject, DeleteObject, and PutObject API operations)

  • AWS Lambda function execution activity (the Invoke API)

Data events are disabled 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 to a trail. For more information, see Creating a Trail and Data Events.

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

Logging Data Events with the AWS Management Console

  1. Open the Trails page of the CloudTrail console and choose the trail name.

    Note

    While you can edit an existing trail to add logging data events, as a best practice, consider creating a separate trail specifically for logging data events.

  2. For Data events, choose Edit.

  3. For Amazon S3 buckets:

    1. For Data event source, choose S3.

    2. You can choose to log All current and future S3 buckets, or you can specify individual buckets or functions. By default, data events are logged for all current and future S3 buckets.

      Note

      Keeping the default All current and future S3 buckets option enables data event logging for all buckets currently in your AWS account and any buckets you create after you finish creating the trail. It also enables logging of data event activity performed by any user or role in your AWS account, even if that activity is performed on a bucket that belongs to another AWS account.

      If the trail applies only to one Region, selecting the Select all S3 buckets in your account option enables data event logging for all buckets in the same Region as your trail and any buckets you create later in that Region. It will not log data events for Amazon S3 buckets in other Regions in your AWS account.

    3. If you leave the default, All current and future S3 buckets, choose to log Read events, Write events, or both.

    4. To select individual buckets, empty the Read and Write check boxes for All current and future S3 buckets. In Individual bucket selection, browse for a bucket on which to log data events. Filter a large number of buckets by typing a bucket prefix for the bucket you want. You can select multiple buckets in this window. Choose Add bucket to log data events for more buckets. Choose to log Read events, such as GetObject, Write events, such as PutObject, or both.

      This setting takes precedence over individual 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 is already selected for the bucket you added. You cannot clear the selection. You can only configure the option for Write.

      To remove a bucket from logging, choose X.

  4. To add another data type on which to log data events, choose Add data event type.

  5. For Lambda functions:

    1. For Data event source, choose Lambda.

    2. In Lambda function, choose All regions to log all Lambda functions, or Input function as ARN to log data events on a specific function.

      To log data events for all Lambda functions in your AWS account, select Log all current and future functions. This setting takes precedence over individual settings you configure for individual functions. All functions are logged, even if all functions are not displayed.

      Note

      If you are creating a trail for all Regions, this selection enables data event logging for all functions currently in your AWS account, and any Lambda functions you might create in any Region after you finish creating the trail. If you are creating a trail for a single Region (done by using the AWS CLI), this selection enables data event logging for all functions currently in that Region in your AWS account, and any Lambda functions you might create in that Region after you finish creating the trail. It does not enable data event logging for Lambda functions created in other Regions.

      Logging data events for all functions also enables logging of data event activity performed by any user or role in your AWS account, even if that activity is performed on a function that belongs to another AWS account.

    3. If you choose Input function as ARN, type the ARN of a Lambda function.

      Note

      If you have more than 15,000 Lambda functions in your account, you cannot view or select all functions in the CloudTrail console when creating a trail. You can still select the option to log all functions, even if they are not displayed. If you want to log data events for specific functions, you can manually add a function if you know its ARN. You can also finish creating the trail in the console, and then use the AWS CLI and the put-event-selectors command to configure data event logging for specific Lambda functions. For more information, see Managing Trails With the AWS CLI.

  6. Choose Update trail.

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

If you are logging data events for specific Amazon S3 buckets, we recommend you do not use an Amazon S3 bucket for which you are logging data events to receive log files that you have specified in the data events section. Using the same Amazon S3 bucket causes your trail to log a data event each time log files are delivered to your Amazon S3 bucket. Log files are aggregated events delivered at intervals, so this is not a 1:1 ratio of event to log file; the event is logged in the next log file. 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. For more information, see How CloudTrail Works.

To avoid logging data events for the Amazon S3 bucket where you receive log files if you configure a trail to log all Amazon S3 data events in your AWS account, consider configuring delivery of log files to an Amazon S3 bucket that belongs to another AWS account. For more information, see Receiving CloudTrail Log Files from Multiple Accounts.

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. Generally, both API callers and resource owners can receive events.

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. Because there are now two copies of the event (one logged in Bob's trail, and one logged in yours), CloudTrail charges for two copies of the data 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. CloudTrail charges for only one copy of this data event.

Example: Logging data events for all buckets, including an S3 bucket used by two AWS accounts

The following example shows the logging behavior when Select all S3 buckets in your account is enabled for trails that collect data events in an AWS account.

  1. In your account, you want your trail to log data events for all S3 buckets. You configure the trail by choosing Read events, Write events, or both for All current and future S3 buckets in Data events.

  2. Bob has a separate account that has been granted access to an S3 bucket in your account. He wants to log data events for the bucket to which he has access. He configures his trail to get data events for all S3 buckets.

  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 event. Because there are now two copies of the event (one logged in Bob's trail, and one logged in yours), CloudTrail charges each account for a copy of the data 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. CloudTrail charges for only one copy of this data event in your account.

  9. A third user, Mary, has access to the S3 bucket, and runs a GetObject operation on the bucket. She has a trail configured to log data events on all S3 buckets in her account. Because she is the API caller, CloudTrail logs a data event in her trail. Though Bob has access to the bucket, he is not the resource owner, so no event is logged in his trail this time. As the resource owner, you receive an event in your trail about the GetObject operation that Mary called. CloudTrail charges your account and Mary's account for each copy of the data event: one in Mary's trail, and one in yours.

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

    Read 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

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

Example: Logging Read and Write 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 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 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.

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.

{ "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.

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.

{ "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 data events for a trail. You can configure your trails to log 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 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.