Create, update, and manage event data stores with the Amazon CLI - Amazon CloudTrail
Available commands for event data storesCreate an event data store with the Amazon CLIImport trail events to an event data store with the Amazon CLIGet an event data store with the Amazon CLIList all event data stores in an account with the Amazon CLIUpdate an event data store with the Amazon CLIStop ingestion on an event data store with the Amazon CLIStart ingestion on an event data store with the Amazon CLIEnable federation on an event data storeDisable federation on an event data storeDelete an event data store with the Amazon CLIRestore an event data store with the Amazon CLI
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Create, update, and manage event data stores with the Amazon CLI

You can use the Amazon CLI to create, update, and manage your event data stores. When using the Amazon CLI, remember that your commands run in the Amazon Web Services Region configured for your profile. If you want to run the commands in a different Region, either change the default Region for your profile, or use the --region parameter with the command.

Available commands for event data stores

Commands for creating and updating event data stores in CloudTrail Lake include:

  • create-event-data-store to create an event data store.

  • get-event-data-store to return information about the event data store including the advanced event selectors configured for the event data store.

  • update-event-data-store to change the configuration of an existing event data store.

  • list-event-data-stores to list the event data stores.

  • delete-event-data-store to delete an event data store.

  • restore-event-data-store to restore an event data store that is pending deletion.

  • start-import to start an import of trail events to an event data store, or retry a failed import.

  • get-import to return information about a specific import.

  • stop-import to stop an import of trail events to an event data store.

  • list-imports to return information on all imports, or a select set of imports by ImportStatus or Destination.

  • list-import-failures to list import failures for the specified import.

  • stop-event-data-store-ingestion to stop event ingestion on an event data store.

  • start-event-data-store-ingestion to restart event ingestion on an event data store.

  • enable-federation to enable federation on an event data store to query the event data store in Amazon Athena.

  • disable-federation to disable federation on an event data store. After you disable federation, you can no longer query against the event data store's data in Amazon Athena. You can continue to query in CloudTrail Lake.

  • put-insight-selectors to add or modify Insights event selectors for an existing event data store, and enable or disable Insights events.

  • get-insight-selectors to return information about Insights event selectors configured for an event data store.

  • add-tags to add one or more tags (key-value pairs) to an existing event data store.

  • remove-tags to remove one or more tags from a event data store.

  • list-tags to return a list of tags associated with a event data store.

For a list of available commands for CloudTrail Lake queries, see Available commands for CloudTrail Lake queries.

For a list of available commands for CloudTrail Lake integrations, see Available commands for CloudTrail Lake integrations.

Create an event data store with the Amazon CLI

Use the create-event-data-store command to create an event data store.

When you create an event data store, the only required parameter is --name, which is used to identify the event data store. You can configure additional optional parameters, including:

  • --advanced-event-selectors - Specifies the type of events to include in the event data store. By default, event data stores log all management events. For more information about advanced event selectors, see AdvancedEventSelector in the CloudTrail API Reference.

  • --kms-key-id - Specifies the AWS KMS key ID to use to encrypt the events delivered by CloudTrail. The value can be an alias name prefixed by alias/, a fully specified ARN to an alias, a fully specified ARN to a key, or a globally unique identifier.

  • --multi-region-enabled - Creates a multi-Region event data store that logs events for all Amazon Web Services Regions in your account. By default, --multi-region-enabled is set, even if the parameter is not added.

  • --organization-enabled - Enables an event data store to collect events for all accounts in an organization. By default, the event data store is not enabled for all accounts in an organization.

  • --billing-mode - Determines the cost for ingesting and storing events, and the default and maximum retention period for the event data store.

    The following are the possible values:

    • EXTENDABLE_RETENTION_PRICING - This billing mode is generally recommended if you ingest less than 25 TB of event data a month and want a flexible retention period of up to 3653 days (about 10 years). The default retention period for this billing mode is 366 days.

    • FIXED_RETENTION_PRICING - This billing mode is recommended if you expect to ingest more than 25 TB of event data per month and need a retention period of up to 2557 days (about 7 years). The default retention period for this billing mode is 2557 days.

    The default value is EXTENDABLE_RETENTION_PRICING.

  • --retention-period - The number of days to keep events in the event data store. Valid values are integers between 7 and 3653 if the --billing-mode is EXTENDABLE_RETENTION_PRICING, or between 7 and 2557 if the --billing-mode is set to FIXED_RETENTION_PRICING. If you do not specify --retention-period, CloudTrail uses the default retention period for the --billing-mode.

  • --start-ingestion - The --start-ingestion parameter starts event ingestion on the event data store when it's created. This parameter is set even if the parameter is not added.

    Specify the --no-start-ingestion if you do not want the event data store to ingest live events. For example, you may want to set this parameter if you are copying events to the event data store and only plan to use the event data to analyze past events. The --no-start-ingestion parameter is only valid if the eventCategory is Management, Data, or ConfigurationItem.

The following examples show how to create different types of event data stores.

Create an event data store for S3 data events with the Amazon CLI

The following example Amazon Command Line Interface (Amazon CLI) create-event-data-store command creates an event data store named my-event-data-store that selects all Amazon S3 data events and is encrypted using a KMS key.

aws cloudtrail create-event-data-store \
--name my-event-data-store \
--kms-key-id "arn:aws:kms:us-east-1:123456789012:alias/KMS_key_alias" \
--advanced-event-selectors '[
        {
            "Name": "Select all S3 data events",
            "FieldSelectors": [
                { "Field": "eventCategory", "Equals": ["Data"] },
                { "Field": "resources.type", "Equals": ["AWS::S3::Object"] },
                { "Field": "resources.ARN", "StartsWith": ["arn:aws:s3"] }
            ]
        }
    ]'

The following is an example response.

{
    "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLE-ee54-4813-92d5-999aeEXAMPLE",
    "Name": "my-event-data-store",
    "Status": "CREATED",
    "AdvancedEventSelectors": [
        {
            "Name": "Select all S3 data events",
            "FieldSelectors": [
                {
                    "Field": "eventCategory",
                    "Equals": [
                        "Data"
                    ]
                },
                {
                    "Field": "resources.type",
                    "Equals": [
                        "AWS::S3::Object"
                    ]
                },
                {
                    "Field": "resources.ARN",
                    "StartsWith": [
                        "arn:aws:s3"
                    ]
                }
            ]
        }
    ],
    "MultiRegionEnabled": true,
    "OrganizationEnabled": false,
    "BillingMode": "EXTENDABLE_RETENTION_PRICING",
    "RetentionPeriod": 366,
    "KmsKeyId": "arn:aws:kms:us-east-1:123456789012:alias/KMS_key_alias",
    "TerminationProtectionEnabled": true,
    "CreatedTimestamp": "2023-11-09T22:19:39.417000-05:00",
    "UpdatedTimestamp": "2023-11-09T22:19:39.603000-05:00"
}

Create an event data store for Amazon Config configuration items with the Amazon CLI

The following example Amazon CLI create-event-data-store command creates an event data store named config-items-eds that selects Amazon Config configuration items. To collect configuration items, specify that the eventCategory field Equals ConfigurationItem in the advanced event selectors.

aws cloudtrail create-event-data-store \
--name config-items-eds \
--advanced-event-selectors '[
    {
        "Name": "Select Amazon Config configuration items",
        "FieldSelectors": [
            { "Field": "eventCategory", "Equals": ["ConfigurationItem"] }
        ]
    }
]'

The following is an example response.

{
    "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLE-ee54-4813-92d5-999aeEXAMPLE",
    "Name": "config-items-eds",
    "Status": "CREATED",
    "AdvancedEventSelectors": [
        {
            "Name": "Select Amazon Config configuration items",
            "FieldSelectors": [
                {
                    "Field": "eventCategory",
                    "Equals": [
                        "ConfigurationItem"
                    ]
                }
            ]
        }
    ],
    "MultiRegionEnabled": true,
    "OrganizationEnabled": false,
    "BillingMode": "EXTENDABLE_RETENTION_PRICING",
    "RetentionPeriod": 366,
    "TerminationProtectionEnabled": true,
    "CreatedTimestamp": "2023-11-07T19:03:24.277000+00:00",
    "UpdatedTimestamp": "2023-11-07T19:03:24.468000+00:00"
}

Create an organization event data store for management events with the Amazon CLI

The following example Amazon CLI create-event-data-store command creates an organization event data store that collects all management events and sets the --billing-mode parameter to FIXED_RETENTION_PRICING.

aws cloudtrail create-event-data-store --name org-management-eds --organization-enabled --billing-mode FIXED_RETENTION_PRICING

The following is an example response.

{
    "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLE6-d493-4914-9182-e52a7934b207",
    "Name": "org-management-eds",
    "Status": "CREATED",
    "AdvancedEventSelectors": [
        {
            "Name": "Default management events",
            "FieldSelectors": [
                {
                    "Field": "eventCategory",
                    "Equals": [
                        "Management"
                    ]
                }
            ]
        }
    ],
    "MultiRegionEnabled": true,
    "OrganizationEnabled": true,
    "BillingMode": "FIXED_RETENTION_PRICING",
    "RetentionPeriod": 2557,
    "TerminationProtectionEnabled": true,
    "CreatedTimestamp": "2023-11-16T15:30:50.689000+00:00",
    "UpdatedTimestamp": "2023-11-16T15:30:50.851000+00:00"
}

Create event data stores for Insights events with the Amazon CLI

To log Insights events in CloudTrail Lake, you need a destination event data store that collects Insights events and a source event data store that enables Insights and logs management events.

This procedure shows you how to create the destination and source event data stores and then enable Insights events.

  1. Run the aws cloudtrail create-event-data-store command to create a destination event data store that collects Insights events. The value for eventCategory must be Insight. Replace retention-period-days with the number of days you would like to retain events in your event data store. Valid values are integers between 7 and 3653 if the --billing-mode is EXTENDABLE_RETENTION_PRICING, or between 7 and 2557 if the --billing-mode is set to FIXED_RETENTION_PRICING. If you do not specify --retention-period, CloudTrail uses the default retention period for the --billing-mode.

    If you are signed in with the management account for an Amazon Organizations organization, include the --organization-enabled parameter if you want to give your delegated administrator access to the event data store.

    aws cloudtrail create-event-data-store \
--name insights-event-data-store \
--no-multi-region-enabled \
--retention-period retention-period-days \
--advanced-event-selectors '[
    {
      "Name": "Select Insights events",
      "FieldSelectors": [
          { "Field": "eventCategory", "Equals": ["Insight"] }
        ]
    }
  ]'

    The following is an example response.

    {
    "Name": "insights-event-data-store",
    "ARN": "arn:aws:cloudtrail:us-east-1:111122223333:eventdatastore/EXAMPLEf852-4e8f-8bd1-bcf6cEXAMPLE",
    "AdvancedEventSelectors": [
        {
           "Name": "Select Insights events",
           "FieldSelectors": [
              {
                  "Field": "eventCategory",
                  "Equals": [
                      "Insight"
                    ]
                }
            ]
        }
    ],
    "MultiRegionEnabled": false,
    "OrganizationEnabled": false,
    "BillingMode": "EXTENDABLE_RETENTION_PRICING",
    "RetentionPeriod": "90",
    "TerminationProtectionEnabled": true,
    "CreatedTimestamp": "2023-05-08T15:22:33.578000+00:00",
    "UpdatedTimestamp": "2023-05-08T15:22:33.714000+00:00"
}

    You will use the ARN (or ID suffix of the ARN) from the response as the value for the --insights-destination parameter in step 3.

  2. Run the aws cloudtrail create-event-data-store command to create a source event data store that logs management events. By default, event data stores log all management events. You don't need to specify the advanced event selectors if you want to log all management events. Replace retention-period-days with the number of days you would like to retain events in your event data store. Valid values are integers between 7 and 3653 if the --billing-mode is EXTENDABLE_RETENTION_PRICING, or between 7 and 2557 if the --billing-mode is set to FIXED_RETENTION_PRICING. If you do not specify --retention-period, CloudTrail uses the default retention period for the --billing-mode. If you are creating an organization event data store, include the --organization-enabled parameter.

    aws cloudtrail create-event-data-store --name source-event-data-store --retention-period retention-period-days

    The following is an example response.

    {
    "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:111122223333:eventdatastore/EXAMPLE9952-4ab9-49c0-b788-f4f3EXAMPLE",
    "Name": "source-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-05-08T15:25:35.578000+00:00",
    "UpdatedTimestamp": "2023-05-08T15:25:35.714000+00:00"
}

    You will use the ARN (or ID suffix of the ARN) from the response as the value for the --event-data-store parameter in step 3.

  3. Run the put-insight-selectors command to enable Insights events. Insights selector values can be ApiCallRateInsight, ApiErrorRateInsight, or both. For the --event-data-store parameter, specify the ARN (or ID suffix of the ARN) of the source event data store that logs management events and will enable Insights. For the --insights-destination parameter, specify the ARN (or ID suffix of the ARN) of the destination event data store that will log Insights events.

    aws cloudtrail put-insight-selectors --event-data-store arn:aws:cloudtrail:us-east-1:111122223333:eventdatastore/EXAMPLE9952-4ab9-49c0-b788-f4f3EXAMPLE --insights-destination arn:aws:cloudtrail:us-east-1:111122223333:eventdatastore/EXAMPLEf852-4e8f-8bd1-bcf6cEXAMPLE --insight-selectors '[{"InsightType": "ApiCallRateInsight"},{"InsightType": "ApiErrorRateInsight"}]'

    The following result shows the Insights event selector that is configured for the event data store.

    {
  "EventDataStoreARN": "arn:aws:cloudtrail:us-east-1:111122223333:eventdatastore/EXAMPLE9952-4ab9-49c0-b788-f4f3EXAMPLE",
  "InsightsDestination": "arn:aws:cloudtrail:us-east-1:111122223333:eventdatastore/EXAMPLEf852-4e8f-8bd1-bcf6cEXAMPLE",
  "InsightSelectors":
      [
         {
            "InsightType": "ApiErrorRateInsight"
         },
         {
            "InsightType": "ApiCallRateInsight"
         }
      ]
}

    After you enable CloudTrail Insights for the first time on an event data store, it can take up to 7 days for CloudTrail to deliver the first Insights event, if unusual activity is detected.

    CloudTrail Insights analyzes management events that occur in a single Region, not globally. A CloudTrail Insights event is generated in the same Region as its supporting management events are generated.

    For an organization event data store, CloudTrail analyzes management events from each member's account instead of analyzing the aggregation of all management events for the organization.

Additional charges apply for ingesting Insights events in CloudTrail Lake. You will be charged separately if you enable Insights for both trails and event data stores. For information about CloudTrail pricing, see Amazon CloudTrail Pricing.

Import trail events to an event data store with the Amazon CLI

In the Amazon CLI, you can import trail events to an event data store. The procedure in this section demonstrates how to create and configure an event data store by running the create-event-data-store command and then import the events to that event data store by using the start-import command. For more information about importing trail events including information about considerations and required permissions, see Copy trail events to an event data store.

Preparing to import trail events

Before you import trail events, make the following preparations.

  • Be sure you have a role with the required permissions to import trail events to an event data store.

  • Determine the --billing-mode value you want to specify for the event data store. The --billing-mode determines the cost of ingesting and storing events, and the default and maximum retention period for the event data store.

    When you import trail events to CloudTrail Lake, CloudTrail unzips the logs that are stored in gzip (compressed) format. Then CloudTrail copies the events contained in the logs to your event data store. The size of the uncompressed data could be greater than the actual Amazon S3 storage size. To get a general estimate of the size of the uncompressed data, multiply the size of the logs in the S3 bucket by 10. You can use this estimate to choose the --billing-mode value for your use case.

  • Determine the value you want to specify for the --retention-period. CloudTrail will not copy an event if its eventTime is older than the specified retention period.

    To determine the appropriate retention period, take the sum of the oldest event you want to copy in days and the number of days you want to retain the events in the event data store as demonstrated in this equation:

    Retention period = oldest-event-in-days + number-days-to-retain

    For example, if the oldest event you're copying is 45 days old and you want to keep the events in the event data store for a further 45 days, you would set the retention period to 90 days.

  • Decide whether you want to use the event data store to analyze any future events. If you don't want to ingest any future events, include the --no-start-ingestion parameter when you create the event data store. By default, event data store's begin ingesting events when they're created.

To create an event data store and import trail events to that event data store

  1. Run the create-event-data-store command to create the new event data store. In this example, the --retention-period is set to 120 because the oldest event being copied is 90 days old and we want to retain the events for 30 days. The --no-start-ingestion parameter is set because we don't want to ingest any future events. In this example, --billing-mode wasn't set, because we are using the default value EXTENDABLE_RETENTION_PRICING as we expect to ingest less than 25 TB of event data.

    Note

    If you're creating the event data store to replace your trail, we recommend configuring the --advanced-event-selectors to match the event selectors of your trail to ensure you have the same event coverage. By default, event data stores log all management events.

    aws cloudtrail create-event-data-store  --name import-trail-eds  --retention-period 120 --no-start-ingestion

    The following is the example response:

    {
    "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLEa-4357-45cd-bce5-17ec652719d9",
    "Name": "import-trail-eds",
    "Status": "CREATED",
    "AdvancedEventSelectors": [
        {
            "Name": "Default management events",
            "FieldSelectors": [
                {
                    "Field": "eventCategory",
                    "Equals": [
                        "Management"
                    ]
                }
            ]
        }
    ],
    "MultiRegionEnabled": true,
    "OrganizationEnabled": false,
    "BillingMode": "EXTENDABLE_RETENTION_PRICING",
    "RetentionPeriod": 120,
    "TerminationProtectionEnabled": true,
    "CreatedTimestamp": "2023-11-09T16:52:25.444000+00:00",
    "UpdatedTimestamp": "2023-11-09T16:52:25.569000+00:00"
}

    The initial Status is CREATED so we'll run the get-event-data-store command to verify ingestion is stopped.

    aws cloudtrail get-event-data-store --event-data-store eds-id

    The response shows the Status is now STOPPED_INGESTION, which indicates the event data store is not ingesting live events.

    {
    "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLEa-4357-45cd-bce5-17ec652719d9",
    "Name": "import-trail-eds",
    "Status": "STOPPED_INGESTION",
    "AdvancedEventSelectors": [
        {
            "Name": "Default management events",
            "FieldSelectors": [
                {
                    "Field": "eventCategory",
                    "Equals": [
                        "Management"
                    ]
                }
            ]
        }
    ],
    "MultiRegionEnabled": true,
    "OrganizationEnabled": false,
    "BillingMode": "EXTENDABLE_RETENTION_PRICING",
    "RetentionPeriod": 120,
    "TerminationProtectionEnabled": true,
    "CreatedTimestamp": "2023-11-09T16:52:25.444000+00:00",
    "UpdatedTimestamp": "2023-11-09T16:52:25.569000+00:00"
}

  2. Run the start-import command to import the trail events to the event data store created in step 1. Specify the ARN (or ID suffix of the ARN) of the event data store as the value for the --destinations parameter. For --start-event-time specify the eventTime for the oldest event you want to copy and for --end-event-time specify the eventTime of the newest event you want to copy. For --import-source specify the S3 URI for the S3 bucket containing your trail logs, the Amazon Web Services Region for the S3 bucket, and the ARN of the role used for importing trail events. 

    aws cloudtrail start-import \
--destinations ["arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLEa-4357-45cd-bce5-17ec652719d9"] \
--start-event-time 2023-08-11T16:08:12.934000+00:00 \
--end-event-time 2023-11-09T17:08:20.705000+00:00 \
--import-source {"S3": {"S3LocationUri": "s3://aws-cloudtrail-logs-123456789012-612ff1f6/AWSLogs/123456789012/CloudTrail/","S3BucketRegion":"us-east-1","S3BucketAccessRoleArn": "arn:aws:iam::123456789012:role/service-role/CloudTrailLake-us-east-1-copy-events-eds"}}

    The following is an example response.

    {
   "CreatedTimestamp": "2023-11-09T17:08:20.705000+00:00",
   "Destinations": [
        "arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLEa-4357-45cd-bce5-17ec652719d9"
    ],
   "EndEventTime": "2023-11-09T17:08:20.705000+00:00",
   "ImportId": "EXAMPLEe-7be2-4658-9204-b38c3257fcd1",
   "ImportSource": { 
      "S3": { 
         "S3BucketAccessRoleArn": "arn:aws:iam::123456789012:role/service-role/CloudTrailLake-us-east-1-copy-events-eds",
         "S3BucketRegion":"us-east-1",
         "S3LocationUri": "s3://aws-cloudtrail-logs-123456789012-111ff1f6/AWSLogs/123456789012/CloudTrail/"
      }
   },
   "ImportStatus": "INITIALIZING",
   "StartEventTime": "2023-08-11T16:08:12.934000+00:00",
   "UpdatedTimestamp": "2023-11-09T17:08:20.806000+00:00"
}

  3. Run the get-import command to get information about the import.

    aws cloudtrail get-import --import-id import-id

    The following is an example response.

    {
    "ImportId": "EXAMPLEe-7be2-4658-9204-b38c3EXAMPLE",
    "Destinations": [
        "arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLEa-4357-45cd-bce5-17ec652719d9"
    ],
    "ImportSource": {
        "S3": {
            "S3LocationUri": "s3://aws-cloudtrail-logs-123456789012-111ff1f6/AWSLogs/123456789012/CloudTrail/",
            "S3BucketRegion":"us-east-1",
            "S3BucketAccessRoleArn": "arn:aws:iam::123456789012:role/service-role/CloudTrailLake-us-east-1-copy-events-eds"
        }
    },
    "StartEventTime": "2023-08-11T16:08:12.934000+00:00",
    "EndEventTime": "2023-11-09T17:08:20.705000+00:00",
    "ImportStatus": "COMPLETED",
    "CreatedTimestamp": "2023-11-09T17:08:20.705000+00:00",
    "ImportStatistics": {
        "PrefixesFound": 1548,
        "PrefixesCompleted": 1548,
        "FilesCompleted": 92845,
        "EventsCompleted": 577249,
        "FailedEntries": 0
    }
}

    An import finishes with an ImportStatus of COMPLETED if there were no failures, or FAILED if there were failures.

    If the import had FailedEntries, you can run the list-import-failures command to return a list of failures.

    aws cloudtrail list-import-failures --import-id import-id

    To retry an import that had failures, run the start-import command with only the --import-id parameter. When you retry an import, CloudTrail resumes the import at the location where the failure occurred.

    aws cloudtrail start-import --import-id import-id

Get an event data store with the Amazon CLI

The following example Amazon CLI get-event-data-store command returns information about the event data store specified by the required --event-data-store parameter, which accepts an ARN or the ID suffix of the ARN.

aws cloudtrail get-event-data-store
--event-data-store arn:aws:cloudtrail:us-east-1:123456789012: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:123456789012:eventdatastore/EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE",
    "Name": "s3-data-events-eds",
    "Status": "ENABLED",
    "AdvancedEventSelectors": [
        {
            "Name": "Log DeleteObject API calls for a specific S3 bucket",
            "FieldSelectors": [
                {
                    "Field": "eventCategory",
                    "Equals": [
                        "Data"
                    ]
                },
                {
                    "Field": "eventName",
                    "Equals": [
                        "DeleteObject"
                    ]
                },
                {
                    "Field": "resources.ARN",
                    "StartsWith": [
                        "arn:aws:s3:::bucketName"
                    ]
                },
                {
                    "Field": "readOnly",
                    "Equals": [
                        "false"
                    ]
                },
                {
                    "Field": "resources.type",
                    "Equals": [
                        "AWS::S3::Object"
                    ]
                }
            ]
        }
    ],
    "MultiRegionEnabled": true,
    "OrganizationEnabled": false,
    "BillingMode": "FIXED_RETENTION_PRICING",
    "RetentionPeriod": 2557,
    "TerminationProtectionEnabled": true,
    "CreatedTimestamp": "2023-11-09T22:20:36.344000+00:00",
    "UpdatedTimestamp": "2023-11-09T22:20:36.476000+00:00"
}

List all event data stores in an account with the Amazon CLI

The following example Amazon CLI list-event-data-stores command returns information about all event data stores in an account, in the current Region. Optional parameters include --max-results, to specify a maximum number of results that you want the command to return on a single page. If there are more results than your specified --max-results value, run the command again adding the returned NextToken value to get the next page of results.

aws cloudtrail list-event-data-stores

The following is an example response.

{
    "EventDataStores": [
        {
            "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLE7-cad6-4357-a84b-318f9868e969",
            "Name": "management-events-eds"
        },
        {
            "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLE6-88e1-43b7-b066-9c046b4fd47a",
            "Name": "config-items-eds"
        },
        {
            "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLEf-b314-4c85-964e-3e43b1e8c3b4",
            "Name": "s3-data-events"
        }
    ]
}

Update an event data store with the Amazon CLI

The following examples show how to update an event data store.

Update the billing mode with the Amazon CLI

The --billing-mode for the event data store determines the cost for ingesting and storing events, and the default and maximum retention period for the event data store. If an event data store's --billing-mode is set to FIXED_RETENTION_PRICING, you can change the value to EXTENDABLE_RETENTION_PRICING. EXTENDABLE_RETENTION_PRICING is generally recommended if your event data store ingests less than 25 TB of event data per month and you want a flexible retention period of up to 3653 days. For information about pricing, see Amazon CloudTrail Pricing and Managing CloudTrail Lake costs.

Note

You cannot change the --billing-mode value from EXTENDABLE_RETENTION_PRICING to FIXED_RETENTION_PRICING. If the event data store's billing mode is set to EXTENDABLE_RETENTION_PRICING and you want to use FIXED_RETENTION_PRICING instead, you can stop ingestion on the event data store and create a new event data store that uses FIXED_RETENTION_PRICING.

The following example Amazon CLI update-event-data-store command changes the --billing-mode for the event data store from FIXED_RETENTION_PRICING to EXTENDABLE_RETENTION_PRICING. The required --event-data-store parameter value is an ARN (or the ID suffix of the ARN) and is required; other parameters are optional. 

aws cloudtrail update-event-data-store \
--region us-east-1 \
--event-data-store arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE \
--billing-mode EXTENDABLE_RETENTION_PRICING

The following is an example response.

{
    "EventDataStoreArn": "event-data-store arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE",
    "Name": "management-events-eds",
    "Status": "ENABLED",
    "AdvancedEventSelectors": [
        {
            "Name": "Default management events",
            "FieldSelectors": [
                {
                    "Field": "eventCategory",
                    "Equals": [
                        "Management"
                    ]
                }
            ]
        }
    ],
    "MultiRegionEnabled": true,
    "OrganizationEnabled": false,
    "BillingMode": "EXTENDABLE_RETENTION_PRICING",
    "RetentionPeriod": 2557,
    "TerminationProtectionEnabled": true,
    "CreatedTimestamp": "2023-10-27T10:55:55.384000-04:00",
    "UpdatedTimestamp": "2023-10-27T10:57:05.549000-04:00"
}

Update the retention mode, enable termination protection, and specify a Amazon KMS key with the Amazon CLI

The following example Amazon CLI update-event-data-store command updates an event data store to change its retention period to 100 days, and enable termination protection. The required --event-data-store parameter value is an ARN (or the ID suffix of the ARN) and is required; other parameters are optional. In this example, the --retention-period parameter is added to change the retention period to 100 days. Optionally, you can choose to enable Amazon Key Management Service encryption and specify an Amazon KMS key by adding --kms-key-id to the command, and specifying a KMS key ARN as the value. --termination-protection-enabled is added to enable termination protection on an event data store that did not have termination protection enabled.

An event data store that logs events from outside Amazon cannot be updated to log Amazon events. Similarly, an event data store that logs Amazon events cannot be updated to log events from outside Amazon.

Note

If you decrease the retention period of an event data store, CloudTrail will remove any events with an eventTime older than the new retention period. For example, if the previous retention period was 365 days and you decrease it to 100 days, CloudTrail will remove events with an eventTime older than 100 days.

aws cloudtrail update-event-data-store \
--event-data-store arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE \
--retention-period 100 \
--kms-key-id "arn:aws:kms:us-east-1:0123456789:alias/KMS_key_alias" \
--termination-protection-enabled

The following is an example response.

{
    "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLE-ee54-4813-92d5-999aeEXAMPLE",
    "Name": "my-event-data-store",
    "Status": "ENABLED",
    "AdvancedEventSelectors": [
        {
            "Name": "Select all S3 data events",
            "FieldSelectors": [
                {
                    "Field": "eventCategory",
                    "Equals": [
                        "Data"
                    ]
                },
                {
                    "Field": "resources.type",
                    "Equals": [
                        "AWS::S3::Object"
                    ]
                },
                {
                    "Field": "resources.ARN",
                    "StartsWith": [
                        "arn:aws:s3"
                    ]
                }
            ]
        }
    ],
    "MultiRegionEnabled": true,
    "OrganizationEnabled": false,
    "BillingMode": "EXTENDABLE_RETENTION_PRICING",
    "RetentionPeriod": 100,
    "KmsKeyId": "arn:aws:kms:us-east-1:0123456789:alias/KMS_key_alias",
    "TerminationProtectionEnabled": true,
    "CreatedTimestamp": "2023-10-27T10:55:55.384000-04:00",
    "UpdatedTimestamp": "2023-10-27T10:57:05.549000-04:00"
}

Disable termination protection with the Amazon CLI

By default, termination protection is enabled on an event data store to protect the event data store from accidental deletion. You cannot delete an event data store when termination protection is enabled. If you want to delete the event data store, you must first disable termination protection.

The following example Amazon CLI update-event-data-store command disables termination protection by passing the --no-termination-protection-enabled parameter.

aws cloudtrail update-event-data-store \
--region us-east-1 \
--no-termination-protection-enabled \
--event-data-store arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE

The following is an example response.

{
    "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE",
    "Name": "management-events-eds",
    "Status": "ENABLED",
    "AdvancedEventSelectors": [
        {
            "Name": "Default management events",
            "FieldSelectors": [
                {
                    "Field": "eventCategory",
                    "Equals": [
                        "Management"
                    ]
                }
            ]
        }
    ],
    "MultiRegionEnabled": true,
    "OrganizationEnabled": false,
    "BillingMode": "EXTENDABLE_RETENTION_PRICING",
    "RetentionPeriod": 366,
    "TerminationProtectionEnabled": false,
    "CreatedTimestamp": "2023-10-27T10:55:55.384000-04:00",
    "UpdatedTimestamp": "2023-10-27T10:57:05.549000-04:00"
}

Stop ingestion on an event data store with the Amazon CLI

The following example Amazon CLI stop-event-data-store-ingestion command stops an event data store from ingesting events. To stop ingestion, the event data store Status must be ENABLED and the eventCategory must be Management, Data, or ConfigurationItem. The event data store is specified by --event-data-store, which accepts an event data store ARN, or the ID suffix of the ARN. After you run stop-event-data-store-ingestion, the state of the event data store changes to STOPPED_INGESTION.

The event data store does count towards your account maximum of ten event data stores when its state is STOPPED_INGESTION.

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

There is no response if the operation is successful.

Start ingestion on an event data store with the Amazon CLI

The following example Amazon CLI start-event-data-store-ingestion command starts event ingestion on an event data store. To start ingestion, the event data store Status must be STOPPED_INGESTION and the eventCategory must be Management, Data, or ConfigurationItem. The event data store is specified by --event-data-store, which accepts an event data store ARN, or the ID suffix of the ARN. After you run start-event-data-store-ingestion, the state of the event data store changes to ENABLED.

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

There is no response if the operation is successful.

Enable federation on an event data store

To enable federation, run the aws cloudtrail enable-federation command, providing the required --event-data-store and --role parameters. For --event-data-store, provide the event data store ARN (or the ID suffix of the ARN). For --role, provide the ARN for your federation role. The role must exist in your account and provide the required minimum permissions.

aws cloudtrail enable-federation
--event-data-store arn:aws:cloudtrail:region:account-id:eventdatastore/eds-id
--role arn:aws:iam::account-id:role/federation-role-name

This example shows how a delegated administrator can enable federation on an organization event data store by specifying the ARN of the event data store in the management account and the ARN of the federation role in the delegated administrator account.

aws cloudtrail enable-federation
--event-data-store arn:aws:cloudtrail:region:management-account-id:eventdatastore/eds-id
--role arn:aws:iam::delegated-administrator-account-id:role/federation-role-name

Disable federation on an event data store

To disable federation on the event data store, run the aws cloudtrail disable-federation command. The event data store is specified by --event-data-store, which accepts an event data store ARN or the ID suffix of the ARN.

aws cloudtrail disable-federation
--event-data-store arn:aws:cloudtrail:region:account-id:eventdatastore/eds-id
Note

If this is an organization event data store, use the account ID for the management account.

Delete an event data store with the Amazon CLI

The following example Amazon CLI delete-event-data-store command disables the event data store specified by --event-data-store, which accepts an event data store ARN, or the ID suffix of the ARN. After you run delete-event-data-store, the final state of the event data store is PENDING_DELETION, and the event data store is automatically deleted after a wait period of 7 days.

After you run delete-event-data-store on an event data store, you cannot run list-queries, describe-query, or get-query-results on queries that are using the disabled data store. The event data store does count towards your account maximum of ten event data stores when it is pending deletion.

Note

You can't delete an event data store if --termination-protection-enabled is set or its FederationStatus is ENABLED.

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

There is no response if the operation is successful.

Restore an event data store with the Amazon CLI

The following example Amazon CLI restore-event-data-store command restores an event data store that is pending deletion. The event data store is specified by --event-data-store, which accepts an event data store ARN or the ID suffix of the ARN. You can only restore a deleted event data store within the seven-day wait period after deletion.

aws cloudtrail restore-event-data-store
--event-data-store EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE

The response includes information about the event data store, including its ARN, advanced event selectors, and the status of restoration.