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, Insights, and management events to CloudWatch Logs. For more information, see Working with CloudTrail log files.
Note
Only the management account can configure
a CloudWatch Logs log group for an organization trail using the console. The delegated administrator can configure a CloudWatch Logs
log group using the AWS CLI or CloudTrail CreateTrail
or UpdateTrail
API operations.
To send events to a CloudWatch Logs log group:
-
Make sure you have sufficient permissions to create or specify an IAM role. For more information, see Granting permission to view and configure Amazon CloudWatch Logs information on the CloudTrail console.
-
If you're configuring the CloudWatch Logs log group using the AWS CLI, make sure you have sufficient permissions to create a CloudWatch Logs log stream in the log group you specify and to deliver CloudTrail events to that log stream. For more information, see Creating a policy document.
-
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 for an existing trail
-
Make sure you log in with an administrative user or role with sufficient permissions to configure CloudWatch Logs integration. For more information, see Granting permission to view and configure Amazon CloudWatch Logs information on the CloudTrail console.
Note
Only the management account can configure a CloudWatch Logs log group for an organization trail using the console. The delegated administrator can configure a CloudWatch Logs log group using the AWS CLI or CloudTrail
CreateTrail
orUpdateTrail
API operations. 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.
-
In CloudWatch Logs, choose Edit.
-
For CloudWatch Logs, choose Enabled.
-
For Log group name, choose New to create a new log group, or Existing to use an existing one. If you choose New, CloudTrail specifies a name for the new log group for you, or you can type a name. For more information about naming, see CloudWatch log group and log stream naming for CloudTrail.
-
If you choose Existing, choose a log group from the drop-down list.
-
For Role name, choose New to create a new IAM role for permissions to send logs to CloudWatch Logs. Choose Existing to choose an existing IAM role from the drop-down list. The policy statement for the new or existing role is displayed when you expand Policy document. For more information about this role, see Role policy document for CloudTrail to use CloudWatch Logs for monitoring.
Note
When you configure a trail, you can choose an S3 bucket and SNS topic that belong to another account. However, if you want CloudTrail to deliver events to a CloudWatch Logs log group, you must choose a log group that exists in your current account.
-
Choose Save changes.
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.
-
To verify the role, go to the AWS Identity and Access Management console at https://console.aws.amazon.com/iam/
. -
Choose Roles and then choose the CloudTrail_CloudWatchLogs_Role.
-
From the Permissions tab, expand the policy to view its contents.
-
-
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 an average of about 5 minutes of an API call. This time is not
guaranteed. Review the AWS CloudTrail Service
Level Agreement
To view events in the CloudWatch console
Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/
. -
In the left navigation pane, under Logs, choose Log groups.
-
Choose the log group that you specified for your trail.
-
Choose the log stream that you want to view.
-
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-arnlog_group_arn
--cloud-watch-logs-role-arnrole_arn
For more information about the AWS CLI commands, see the AWS CloudTrail Command Line Reference.
Limitation
CloudWatch Logs and EventBridge each allow a maximum event size of 256 KB. Although most service events have a maximum size of 256 KB, some services still have events that are larger. CloudTrail does not send these events to CloudWatch Logs or EventBridge.
Starting with CloudTrail event version 1.05, events have a maximum size of 256 KB. This is to help prevent exploitation by malicious actors, and allow events to be consumed by other AWS services, such as CloudWatch Logs and EventBridge.