Menu
AWS CloudTrail
User Guide (Version 1.0)

Sending CloudTrail Events to CloudWatch Logs

To configure your trail to send logs to a CloudWatch Logs log group:

  • Create a log group or specify an existing one.

  • Specify an IAM role.

  • Attach a role policy or use the default.

Note

You must create a trail before you can configure it to send log events to CloudWatch Logs. To create a trail, see Creating a Trail for the First Time or Creating and Updating a Trail with the AWS Command Line Interface. Create an action policy to grant your IAM role permissions to create a log group, change the log group, and assume the role. For more information, see Granting Custom Permissions for CloudTrail Users.

Configuring CloudWatch Logs Monitoring Using the Console

You can use the AWS Management Console to configure your trail to send log events to CloudWatch Logs for monitoring.

Creating a Log Group or Specifying an Existing Log Group

CloudTrail uses a CloudWatch Logs log group as a delivery endpoint for log events. You can create a log group or specify an existing one.

To specify a log group using the console

  1. Navigate to the CloudTrail Trails page.

  2. Choose the name of the trail you want to configure. If you choose a trail that applies to all regions, you will be redirected to the region in which the trail was created. You can create a log group or choose an existing log group in the same region as the trail.

  3. For CloudWatch Logs (Optional):

    1. If you are creating a log group for CloudWatch Logs, choose Configure.

    2. If you already have one or more CloudWatch logs configured, choose the Edit (pencil) icon.

  4. For New or existing log group, type a log group name to organize CloudTrail events, and then choose Continue.

    Note

    For recommended log group naming conventions, see Log Group and Log Stream Names.

Specifying an IAM Role

You can specify a role for CloudTrail to assume to deliver events to the log stream.

To specify a role using the console

  1. By default, the CloudTrail_CloudWatchLogs_Role is selected for you. The default role policy contains the permissions required for creating a CloudWatch Logs log stream in a log group that you specify and for delivering CloudTrail events to that log stream.

    1. To verify the role, navigate to the AWS Identity and Access Management console.

    2. Choose Roles, and then choose the CloudTrail_CloudWatchLogs_Role.

    3. To see the contents of the role policy, choose View Policy Document.

  2. You can specify another role, but you must attach the appropriate role policy to the existing role if you want to use it to send log events to CloudWatch Logs. For more information, see Role Policy Document for CloudTrail to Use CloudWatch Logs for Monitoring.

The trail is configured to use the log group and role that you specified to send events to CloudWatch Logs. If your trail applies to all regions, events from all regions will be sent to the CloudWatch Logs log group you specified.

Configuring CloudWatch Logs Monitoring Using the AWS CLI

You can use the AWS CLI to configure CloudTrail to send log events to CloudWatch Logs for monitoring.

Creating a Log Group

  1. If you don't have an existing log group, create a CloudWatch Logs log group as a delivery endpoint for log events using the CloudWatch Logs create-log-group command.

    Copy
    aws logs create-log-group --log-group-name name

    The following example creates a log group named CloudTrail/logs:

    Copy
    aws logs create-log-group --log-group-name CloudTrail/logs
  2. Retrieve the log group Amazon Resource Name (ARN).

    Copy
    aws logs describe-log-groups

Creating a Role

Create a role for CloudTrail that enables it to send events to the CloudWatch Logs log group. The IAM create-role command takes two parameters: a role name and a file path to an assume role policy document in JSON format. The policy document that you use gives AssumeRole permissions to CloudTrail. The create-role command creates the role with the required permissions.

To create the JSON file that will contain the policy document, open a text editor and save the following policy contents in a file called assume_role_policy_document.json.

Copy
{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "cloudtrail.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }

Run the following command to create the role with AssumeRole permissions for CloudTrail.

Copy
aws iam create-role --role-name role_name --assume-role-policy-document file://<path to assume_role_policy_document>.json

When the command completes, take a note of the role ARN in the output.

Creating a Policy Document

Create the following role policy document for CloudTrail. This document grants CloudTrail the permissions required to create a CloudWatch Logs log stream in the log group you specify and to deliver CloudTrail events to that log stream.

Copy
{ "Version": "2012-10-17", "Statement": [ { "Sid": "AWSCloudTrailCreateLogStream2014110", "Effect": "Allow", "Action": [ "logs:CreateLogStream" ], "Resource": [ "arn:aws:logs:region:accountID:log-group:log_group_name:log-stream:accountID_CloudTrail_region*" ] }, { "Sid": "AWSCloudTrailPutLogEvents20141101", "Effect": "Allow", "Action": [ "logs:PutLogEvents" ], "Resource": [ "arn:aws:logs:region:accountID:log-group:log_group_name:log-stream:accountID_CloudTrail_region*" ] } ] }

Save the policy document in a file called role-policy-document.json.

Run the following command to apply the policy to the role.

Copy
aws iam put-role-policy --role-name role_name --policy-name cloudtrail-policy --policy-document file://<path to role-policy-document>.json

Updating the Trail

Update the trail with the log group and role information using the CloudTrail update-trail command.

Copy
aws cloudtrail update-trail --name trail_name --cloud-watch-logs-log-group-arn log_group_arn --cloud-watch-logs-role-arn role_arn

For more information about the AWS CLI commands, see the AWS CloudTrail Command Line Reference.

Limitation

Because CloudWatch Logs has an event size limitation of 256 KB, CloudTrail does not send events larger than 256 KB to CloudWatch Logs. For example, a call to the EC2 RunInstances API to launch 500 instances will exceed the 256 KB limit. CloudTrail does not send the event to CloudWatch Logs. To ensure that CloudTrail sends events to CloudWatch Logs, break large requests into smaller batches.

Note

If your trails are configured to send events to Amazon CloudWatch Logs, CloudTrail sends only the events that match your event selectors. CloudTrail supports sending only management events to CloudWatch Logs. For more information, see Management Events.