Sending Events to CloudWatch Logs

When you configure your trail to send events to CloudWatch Logs, CloudTrail sends only the events that match your trail settings. For example, if you configure your trail to log data events only, your trail sends data events only to your CloudWatch Logs log group. CloudTrail supports sending data and management events to CloudWatch Logs. For more information, see Logging Data and Management Events for Trails.

To send events to a CloudWatch Logs log group:

Create a new trail or specify an existing one. For more information, see Creating and Updating a Trail with the Console.
Create a log group or specify an existing one.
Specify an IAM role. If you are modifying an existing IAM role for an organization trail, you must manually update the policy to allow logging for the organization trail. For more information, see this policy example and Creating a Trail for an Organization.
Attach a role policy or use the default.

Contents

Configuring CloudWatch Logs Monitoring with the Console

You can use the AWS Management Console to configure your trail to send 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 create or specify a log group

Open the CloudTrail console at https://console.aws.amazon.com/cloudtrail/.
Choose the trail name. 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.

Note

A trail that applies to all regions sends log files from all regions to the CloudWatch Logs log group that you specify.
For CloudWatch Logs, choose Configure.
For New or existing log group, type the log group name , and then choose Continue. For more information, see CloudWatch Log Group and Log Stream Naming for CloudTrail.
For the IAM role, choose an existing role or create one. If you create an IAM role, type a role name.
Choose Allow to grant CloudTrail permissions to create a CloudWatch Logs log stream and deliver events.

Specifying an IAM Role

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

To specify a role

By default, the CloudTrail_CloudWatchLogs_Role is specified for you. The default role policy has the required permissions to create a CloudWatch Logs log stream in a log group that you specify, and to deliver CloudTrail events to that log stream.

Note

If you want to use this role for a log group for an organization trail, you must manually modify the policy after you create the role. For more information, see this policy example and Creating a Trail for an Organization.
1. To verify the role, go to the AWS Identity and Access Management console at https://console.aws.amazon.com/iam/.
2. Choose Roles and then choose the CloudTrail_CloudWatchLogs_Role.
3. To see the contents of the role policy, choose View Policy Document.
You can specify another role, but you must attach the required role policy to the existing role if you want to use it to send events to CloudWatch Logs. For more information, see Role Policy Document for CloudTrail to Use CloudWatch Logs for Monitoring.

Viewing Events in the CloudWatch Console

After you configure your trail to send events to your CloudWatch Logs log group, you can view the events in the CloudWatch console. CloudTrail typically delivers events to your log group within a few minutes of an API call.

To view events in the CloudWatch console

Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.
Choose Logs.
Choose the log group that you specified for your trail.
Choose the log stream name.
To see the details of the event that your trail logged, choose an event.

Note

The Time (UTC) column in the CloudWatch console shows when the event was delivered to your log group. To see the actual time that the event was logged by CloudTrail, see the eventTime field.

Configuring CloudWatch Logs Monitoring with the AWS CLI

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

Creating a Log Group

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.
```
aws logs create-log-group --log-group-name name
```
The following example creates a log group named CloudTrail/logs:
```
aws logs create-log-group --log-group-name CloudTrail/logs
```
Retrieve the log group Amazon Resource Name (ARN).
```
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.


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


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.


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

If you're creating a policy that might be used for organization trails as well, you will need to configure it slightly differently. For example, the following policy 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 for both trails in the AWS account 111111111111 and for organization trails created in the 111111111111 account that are applied to the AWS Organizations organization with the ID of o-exampleorgid:


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AWSCloudTrailCreateLogStream20141101",
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogStream"
            ],
            "Resource": [
                "arn:aws:logs:us-east-2:111111111111:log-group:CloudTrail/DefaultLogGroupTest:log-stream:111111111111_CloudTrail_us-east-2*",
                "arn:aws:logs:us-east-2:111111111111:log-group:CloudTrail/DefaultLogGroupTest:log-stream:o-exampleorgid_*",
            ]
        },
        {
            "Sid": "AWSCloudTrailPutLogEvents20141101",
            "Effect": "Allow",
            "Action": [
                "logs:PutLogEvents"
            ],
            "Resource": [
                "arn:aws:logs:us-east-2:111111111111:log-group:CloudTrail/DefaultLogGroupTest:log-stream:111111111111_CloudTrail_us-east-2*",             
                "arn:aws:logs:us-east-2:111111111111:log-group:CloudTrail/DefaultLogGroupTest:log-stream:o-exampleorgid_*",
            ]
        }
    ]
}

For more information about organization trails, see Creating a Trail for an Organization.

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


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.


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.

Warning Javascript is disabled or is unavailable in your browser.

To use the AWS Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

« Previous Next »