How do I use AWS CloudTrail to track API calls to my Amazon EC2 instances?

Last updated: 2021-07-20

I want to track API calls that run, stop, start, and terminate my Amazon Elastic Compute Cloud (Amazon EC2) instances. How do I search for API calls to my Amazon EC2 instances using AWS CloudTrail?

Short description

AWS CloudTrail allows you to identify and track four types of API calls (event types) made to your AWS account:

To review these types of API calls after they've been made to your account, you can use any of the following methods.

Note: You can view event history for your account up to the last 90 days.

Resolution

To track API calls using CloudTrail event history

1.    Open the CloudTrail console.

2.    Choose Event history.

3.    For Filter, select Event name from the dropdown list.

4.    For Enter event name, enter the event type that you want to search for. Then, choose the event type.

5.    For Time range, enter the desired time range that you want to track the event type for.

6.    Choose Apply.

For more information, see Viewing events with CloudTrail event history and Viewing Cloudtrail events in the CloudTrail console.

To track API calls using Amazon Athena queries

Follow the instructions in How do I automatically create tables in Amazon Athena to search through AWS CloudTrail logs?

The following are example queries for the RunInstances API call. You can use similar queries for any of the supported event types.

Important: Replace cloudtrail-logs with your Athena table name before running any of the following query examples.

Example query to return all available event information for the RunInstances API call

SELECT *
FROM cloudtrail-logs
WHERE eventName = 'RunInstances'

Example query to return filtered event information for the RunInstances API call

SELECT userIdentity.username, eventTime, eventName
FROM cloudtrail-logs
WHERE eventName = 'RunInstances'

Example query to return event information for the APIs that end with the string "Instances" from a point in time to the current date

Important: Replace '2021-07-01T00:00:01Z' with the point in time you'd like to return event information from.

SELECT userIdentity.username, eventTime, eventName
FROM cloudtrail-logs
WHERE (eventName LIKE '%Instances') AND eventTime > '2021-07-01T00:00:01Z'

To track API calls using archived Amazon CloudWatch Logs in Amazon Simple Storage Service (Amazon S3)

Important: To log events to an Amazon S3 bucket, you must first create a CloudWatch trail.

1.    Access your CloudTrail log files by following the instructions in Finding your CloudTrail log files.

2.    Download your log files by following the instructions in Downloading your CloudTrail log files.

3.    Search through the logs for the event types that you want to track using jq or another JSON command line processor.

Example jq procedure for searching CloudWatch logs downloaded from Amazon S3 for specific event types

1.    Open a Bash terminal. Then, create the following directory to store the log files:

$ mkdir cloudtrail-logs

4.    Navigate to the new directory. Then, download the CloudTrail logs by running the following command:

Important: Replace the example my_cloudtrail_bucket with your Amazon S3 bucket.

$ cd cloudtrail-logs

$ aws s3 cp s3://my_cloudtrail_bucket/AWSLogs/012345678901/CloudTrail/eu-west-1/2019/08/07 ./ --recursive

5.    Decompress the log files by running the following gzip command:

Important: Replace * with the file name that you want to decompress.

$ gzip -d *

6.    Run a jq query for the event types that you want to search for.

Example jq query to return all available event information for the RunInstances API call

cat * | jq '.Records[] | select(.eventName=="RunInstances")'

Example jq query to return all available event information for the StopInstances and TerminateInstances API calls

cat * | jq '.Records[] | select(.eventName=="StopInstances" or .eventName=="TerminateInstances" )'