Logging management events - AWS CloudTrail
Management eventsRead and write eventsLogging management events with the AWS Management ConsoleLogging management events with the AWS CLILogging management events with the AWS SDKs

Logging management events

By default, trails and event data stores log management events and don't include data or Insights events.

Additional charges apply for data or Insights events. For more information, see AWS CloudTrail Pricing.

Management events

Management events provide visibility into management operations that are performed on resources in your AWS account. These are also known as control plane operations. Example management events include:

  • Configuring security (for example, IAM AttachRolePolicy API operations)

  • Registering devices (for example, Amazon EC2 CreateDefaultVpc API operations)

  • Configuring rules for routing data (for example, Amazon EC2 CreateSubnet API operations)

  • Setting up logging (for example, AWS CloudTrail CreateTrail 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.

By default, trails and event data stores are configured to log management events.

Note

The CloudTrail Event history feature supports only management events. You cannot exclude AWS KMS or Amazon RDS Data API events from Event history; settings that you apply to a trail or event data store do not apply to Event history. For more information, see Working with CloudTrail Event history.

Read and write events

When you configure your trail or event data store to log management events, you can specify whether you want read-only events, write-only events, or both.

  • Read

    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

    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.

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.

  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.

  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 management events with the AWS Management Console

  1. Sign in to the AWS Management Console and open the CloudTrail console at https://console.aws.amazon.com/cloudtrail/.

  2. To update a trail, open the Trails page of the CloudTrail console and choose the trail name.

    To update an event data store, open the Event data stores page of the CloudTrail console and choose the event data store name.

  3. For Management events, choose Edit.

    • Choose if you want your trail or event data store to log Read events, Write events, or both.

    • Choose Exclude AWS KMS events to filter AWS Key Management Service (AWS KMS) events out of your trail or event data store. The default setting is to include all AWS KMS events.

      The option to log or exclude AWS KMS events is available only if you log management events on your trail or event data store. If you choose not to log management events, AWS KMS events are not logged, and you cannot change AWS KMS event logging settings.

      AWS KMS actions such as Encrypt, Decrypt, and GenerateDataKey typically generate a large volume (more than 99%) of events. These actions are now logged as Read events. Low-volume, relevant AWS KMS actions such as Disable, Delete, and ScheduleKey (which typically account for less than 0.5% of AWS KMS event volume) are logged as Write events.

      To exclude high-volume events like Encrypt, Decrypt, and GenerateDataKey, but still log relevant events such as Disable, Delete and ScheduleKey, choose to log Write management events, and clear the check box for Exclude AWS KMS events.

    • Choose Exclude Amazon RDS Data API events to filter Amazon Relational Database Service Data API events out of your trail or event data store. The default setting is to include all Amazon RDS Data API events. For more information about Amazon RDS Data API events, see Logging Data API calls with AWS CloudTrail in the Amazon RDS User Guide for Aurora.

  4. Choose Save changes when you are finished.

Logging management events with the AWS CLI

You can configure your trails or event data stores to log management events using the AWS CLI.

Examples: Logging management events for trails

To view whether your trail is logging management 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, log events from all event sources, and don't log data events.

{
    "TrailARN": "arn:aws:cloudtrail:us-east-1:111122223333:trail/TrailName",
    "AdvancedEventSelectors": [
        {
            "Name": "Management events selector",
            "FieldSelectors": [
                {
                    "Field": "eventCategory",
                    "Equals": [
                        "Management"
                    ]
                }
            ]
        }
    ]
}

You can use either basic or advanced event selectors to log management events. You cannot apply both event selectors and advanced event selectors to a trail. If you apply advanced event selectors to a trail, any existing basic event selectors are overwritten. The following sections provide examples of how to log management events using advanced event selectors and basic event selectors.

Examples: Logging management events for trails using advanced event selectors

The following example creates an advanced event selector for a trail named TrailName to include read-only and write-only management events (by omitting the readOnly selector), but to exclude AWS Key Management Service (AWS KMS) events. Because AWS KMS events are treated as management events, and there can be a high volume of them, they can have a substantial impact on your CloudTrail bill if you have more than one trail that captures management events.

If you choose not to log management events, AWS KMS events are not logged, and you cannot change AWS KMS event logging settings.

To start logging AWS KMS events to a trail again, remove the eventSource selector, and run the command again.

aws cloudtrail put-event-selectors --trail-name TrailName \
--advanced-event-selectors '
[
  {
    "Name": "Log all management events except KMS events",
    "FieldSelectors": [
      { "Field": "eventCategory", "Equals": ["Management"] },
      { "Field": "eventSource", "NotEquals": ["kms.amazonaws.com"] }
    ]
  }
]'

The example returns the advanced event selectors that are configured for the trail.

{
  "AdvancedEventSelectors": [
    {
      "Name": "Log all management events except KMS events",
      "FieldSelectors": [
        {
          "Field": "eventCategory", 
          "Equals": [ "Management" ]
        },
        {
          "Field": "eventSource", 
          "NotEquals": [ "kms.amazonaws.com" ]
        }
      ]
    }
  ],
  "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName"
}

To start logging excluded events to a trail again, remove the eventSource selector, as shown in the following command.

aws cloudtrail put-event-selectors --trail-name TrailName \
--advanced-event-selectors '
[
  {
    "Name": "Log all management events",
    "FieldSelectors": [
      { "Field": "eventCategory", "Equals": ["Management"] }
    ]
  }
]'

The next example creates an advanced event selector for a trail named TrailName to include read-only and write-only management events (by omitting the readOnly selector), but to exclude Amazon RDS Data API management events. To exclude Amazon RDS Data API management events, specify the Amazon RDS Data API event source in the string value for the eventSource field: rdsdata.amazonaws.com.

If you choose not to log management events, Amazon RDS Data API management events are not logged, and you cannot change Amazon RDS Data API event logging settings.

To start logging Amazon RDS Data API management events to a trail again, remove the eventSource selector, and run the command again.

aws cloudtrail put-event-selectors --trail-name TrailName \
--advanced-event-selectors '
[
  {
    "Name": "Log all management events except Amazon RDS Data API management events",
    "FieldSelectors": [
      { "Field": "eventCategory", "Equals": ["Management"] },
      { "Field": "eventSource", "NotEquals": ["rdsdata.amazonaws.com"] }
    ]
  }
]'

The example returns the advanced event selectors that are configured for the trail.

{
  "AdvancedEventSelectors": [
    {
      "Name": "Log all management events except Amazon RDS Data API management events",
      "FieldSelectors": [
        {
          "Field": "eventCategory", 
          "Equals": [ "Management" ]
        },
        {
          "Field": "eventSource", 
          "NotEquals": [ "rdsdata.amazonaws.com" ]
        }
      ]
    }
  ],
  "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName"
}

To start logging excluded events to a trail again, remove the eventSource selector, as shown in the following command.

aws cloudtrail put-event-selectors --trail-name TrailName \
--advanced-event-selectors '
[
  {
    "Name": "Log all management events",
    "FieldSelectors": [
      { "Field": "eventCategory", "Equals": ["Management"] }
    ]
  }
]'

Examples: Logging management events for trails using basic event selectors

To configure your trail to log management events, run the put-event-selectors command. The following example shows how to configure your trail to include all management 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.

{
    "TrailARN": "arn:aws:cloudtrail:us-east-1:111122223333:trail/TrailName",
    "EventSelectors": [
        {
            "ReadWriteType": "All",
            "IncludeManagementEvents": true,
            "DataResources": [
                {
                    "Type": "AWS::S3::Object",
                    "Values": [
                        "arn:aws:s3:::mybucket/prefix",
                        "arn:aws:s3:::mybucket2/prefix2",
                    ]  
                }
            ],
            "ExcludeManagementEventSources": []
        }
    ]
}

To exclude AWS Key Management Service (AWS KMS) events from a trail's logs, run the put-event-selectors command and add the attribute ExcludeManagementEventSources with a value of kms.amazonaws.com. The following example creates an event selector for a trail named TrailName to include read-only and write-only management events, but exclude AWS KMS events. Because AWS KMS can generate a high volume of events, the user in this example might want to limit events to manage the cost of a trail.

aws cloudtrail put-event-selectors --trail-name TrailName --event-selectors '[{"ReadWriteType": "All","ExcludeManagementEventSources": ["kms.amazonaws.com"],"IncludeManagementEvents": true}]'

The example returns the event selector configured for the trail.

{
    "TrailARN": "arn:aws:cloudtrail:us-east-1:111122223333:trail/TrailName",
    "EventSelectors": [
        {
            "ReadWriteType": "All",
            "IncludeManagementEvents": true,
            "DataResources": [],
            "ExcludeManagementEventSources": [
                "kms.amazonaws.com"
            ]
        }
    ]
}

To exclude Amazon RDS Data API management events from a trail's logs, run the put-event-selectors command and add the attribute ExcludeManagementEventSources with a value of rdsdata.amazonaws.com. The following example creates an event selector for a trail named TrailName to include read-only and write-only management events, but exclude Amazon RDS Data API management events. Because Amazon RDS Data API can generate a high volume of management events, the user in this example might want to limit events to manage the cost of a trail.

{
    "TrailARN": "arn:aws:cloudtrail:us-east-1:111122223333:trail/TrailName",
    "EventSelectors": [
        {
            "ReadWriteType": "All",
            "IncludeManagementEvents": true,
            "DataResources": [],
            "ExcludeManagementEventSources": [
                "rdsdata.amazonaws.com"
            ]
        }
    ]
}

To start logging AWS KMS or Amazon RDS Data API management events to a trail again, pass an empty string as the value of ExcludeManagementEventSources, as shown in the following command.

aws cloudtrail put-event-selectors --trail-name TrailName --event-selectors '[{"ReadWriteType": "All","ExcludeManagementEventSources": [],"IncludeManagementEvents": true}]'

To log relevant AWS KMS events to a trail like Disable, Delete and ScheduleKey, but exclude high-volume AWS KMS events like Encrypt, Decrypt, and GenerateDataKey, log write-only management events, and keep the default setting to log AWS KMS events, as shown in the following example.

aws cloudtrail put-event-selectors --trail-name TrailName --event-selectors '[{"ReadWriteType": "WriteOnly","ExcludeManagementEventSources": [],"IncludeManagementEvents": true}]'

Examples: Logging management events for event data stores

To view whether your event data store includes management events, run the get-event-data-store command.

aws cloudtrail get-event-data-store
--event-data-store arn:aws:cloudtrail:us-east-1:12345678910:eventdatastore/EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE

The following is an example response. Creation and last updated times are in timestamp format.

{
    "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:12345678910:eventdatastore/EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE",
    "Name": "myManagementEvents",
    "Status": "ENABLED",
    "AdvancedEventSelectors": [
        {
            "Name": "Management events selector",
            "FieldSelectors": [
                {
                    "Field": "eventCategory",
                    "Equals": [
                        "Management"
                    ]
                }
            ]
        }
    ],
    "MultiRegionEnabled": true,
    "OrganizationEnabled": false,
    "BillingMode": "FIXED_RETENTION_PRICING",
    "RetentionPeriod": 2557,
    "TerminationProtectionEnabled": true,
    "CreatedTimestamp": "2023-02-04T15:56:27.418000+00:00",
    "UpdatedTimestamp": "2023-02-04T15:56:27.544000+00:00"
}

To create an event data store that includes all management events, you run the create-event-data-store command. You do not need to specify any advanced event selectors to include all management events.

aws cloudtrail create-event-data-store
--name my-event-data-store
--retention-period 90\

The following is an example response.

{
    "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:12345678910:eventdatastore/EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE",
    "Name": "my-event-data-store",
    "Status": "CREATED",
    "AdvancedEventSelectors": [
        {
            "Name": "Default management events",
            "FieldSelectors": [
                {
                    "Field": "eventCategory",
                    "Equals": [
                        "Management"
                    ]
                }
            ]
        }
    ],
    "MultiRegionEnabled": true,
    "OrganizationEnabled": false,
    "BillingMode": "EXTENDABLE_RETENTION_PRICING",
    "RetentionPeriod": 90,
    "TerminationProtectionEnabled": true,
    "CreatedTimestamp": "2023-11-13T16:41:57.224000+00:00",
    "UpdatedTimestamp": "2023-11-13T16:41:57.357000+00:00"
}

To create an event data store that excludes AWS Key Management Service (AWS KMS) events, run the create-event-data-store command and specify that eventSource does not equal kms.amazonaws.com. The following example creates an event data store that includes read-only and write-only management events, but excludes AWS KMS events.

aws cloudtrail create-event-data-store --name event-data-store-name --retention-period 90 --advanced-event-selectors '[
    {
        "Name": "Management events selector",
        "FieldSelectors": [
            {"Field": "eventCategory","Equals": ["Management"]},
            {"Field": "eventSource","NotEquals": ["kms.amazonaws.com"]}
        ]
    }
]'

The following is an example response.

{
    "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:12345678910:eventdatastore/EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE",
    "Name": "event-data-store-name",
    "Status": "CREATED",
    "AdvancedEventSelectors": [
        {
            "Name": "Management events selector",
            "FieldSelectors": [
                {
                    "Field": "eventCategory",
                    "Equals": [
                        "Management"
                    ]
                },
                {
                    "Field": "eventSource",
                    "NotEquals": [
                        "kms.amazonaws.com"
                    ]
                }
            ]
        }
    ],
    "MultiRegionEnabled": true,
    "OrganizationEnabled": false,
    "BillingMode": "EXTENDABLE_RETENTION_PRICING",
    "RetentionPeriod": 90,
    "TerminationProtectionEnabled": true,
    "CreatedTimestamp": "2023-11-13T17:02:02.067000+00:00",
    "UpdatedTimestamp": "2023-11-13T17:02:02.241000+00:00"
}

To create an event data store that excludes Amazon RDS Data API management events, run the create-event-data-store command and specify that eventSource does not equal rdsdata.amazonaws.com. The following example creates an event data store that includes read-only and write-only management events, but excludes Amazon RDS Data API events. 

aws cloudtrail create-event-data-store --name event-data-store-name --retention-period 90 --advanced-event-selectors '[
    {
        "Name": "Management events selector",
        "FieldSelectors": [
            {"Field": "eventCategory","Equals": ["Management"]},
            {"Field": "eventSource","NotEquals": ["rdsdata.amazonaws.com"]}
        ]
    }
]'

The following is an example response.

{
    "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:12345678910:eventdatastore/EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE",
    "Name": "my-event-data-store",
    "Status": "CREATED",
    "AdvancedEventSelectors": [
        {
            "Name": "Management events selector",
            "FieldSelectors": [
                {
                    "Field": "eventCategory",
                    "Equals": [
                        "Management"
                    ]
                },
                {
                    "Field": "eventSource",
                    "NotEquals": [
                        "rdsdata.amazonaws.com"
                    ]
                }
            ]
        }
    ],
    "MultiRegionEnabled": true,
    "OrganizationEnabled": false,
    "BillingMode": "EXTENDABLE_RETENTION_PRICING",
    "RetentionPeriod": 90,
    "TerminationProtectionEnabled": true,
    "CreatedTimestamp": "2023-11-13T17:02:02.067000+00:00",
    "UpdatedTimestamp": "2023-11-13T17:02:02.241000+00:00"
}

Logging management events with the AWS SDKs

Use the GetEventSelectors operation to see whether your trail is logging management events for a trail. You can configure your trails to log management events with the PutEventSelectors operation. For more information, see the AWS CloudTrail API Reference.

Run the GetEventDataStore operation to see whether your event data store includes management events. You can configure your event data stores to include management events by running the CreateEventDataStore or UpdateEventDataStore operations. For more information, see Create, update, and manage event data stores with the AWS CLI and the AWS CloudTrail API Reference.