AWS CloudTrail
User Guide (Version 1.0)

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Getting Started with AWS CloudTrail Tutorial

If you're new to AWS CloudTrail, this tutorial helps you learn how to use its features. In this tutorial, you review your recent AWS account activity in the CloudTrail console and examine an event. You then create a trail, which is an ongoing record of management event activity that is stored in an Amazon S3 bucket. Unlike Event history, this ongoing record is not limited to 90 days, logs events in all AWS Regions, and can help you meet your security and auditing needs over time.

Prerequisites

Before you begin, you must complete the following prerequisites and setup:

  • Create an AWS account, if you do not already have one.

    If you do not have an AWS account, complete the following steps to create one.

    To sign up for an AWS account

    1. Open https://portal.aws.amazon.com/billing/signup.

    2. Follow the online instructions.

      Part of the sign-up procedure involves receiving a phone call and entering a verification code on the phone keypad.

  • Create an IAM user for administering CloudTrail. For more information, see Granting Permissions for CloudTrail Administration .

Step 1: Review AWS Account Activity in Event History

CloudTrail is enabled on your AWS account when you create the account. When activity occurs in any AWS service that supports CloudTrail, that activity is recorded in a CloudTrail event along with other AWS service events in Event history. In other words, you can view, search, and download recent events in your AWS account before creating a trail, although creating a trail is vitally important for long-term records and auditing of your AWS account activity. Unlike a trail, Event history is limited to recent events.

  1. Sign in to the AWS Management Console using the IAM user you configured for CloudTrail administration. Open the CloudTrail console at https://console.aws.amazon.com/cloudtrail/home/.

  2. Review the information in your dashboard about the most recent events that have occurred in your AWS account. One of these events should be a ConsoleSignin event, showing that you just signed in to the AWS Management Console.

    
      The CloudTrail dashboard showing recent events
  3. To see more information about an event, expand it.

    
      The CloudTrail dashboard showing expanded information about an event
  4. In the navigation pane, choose Event history. You see a filtered list of events, with the most recent events showing first. The default filter for events is Read only, set to false. You can clear that filter by choosing the delete icon.

    
      The CloudTrail Event history page highlighting the Read only filter
  5. Many more events are shown without the default filter. You can filter events in many ways. For example, to view all console login events, you could choose the Event name filter, and specify ConsoleLogin. The choice of filters is up to you.

    
      The CloudTrail Event history page with the default filter removed, showing a partial list of filter options
  6. You can save event history by downloading it as a file in CSV or JSON format.

    
      The CloudTrail Event history page showing the download options

For more information, see Viewing Events with CloudTrail Event History.

Step 2: Create Your First Trail

While the events provided in the Event history view in the CloudTrail console are useful for reviewing recent activity, they are limited to recent activity, and they do not include all possible events that can be recorded by CloudTrail. Additionally, your view of events in the console is limited to the AWS Region where you are signed in. To create an ongoing record of activity in your AWS account that captures information for all AWS Regions, create a trail. For your first trail, we recommend creating a trail that logs all management events in all AWS Regions, and does not log any data events. Examples of management events include security events such as IAM CreateUser and AttachRolePolicy events, resource events such as RunInstances and CreateBucket, and many more. You will create an Amazon S3 bucket where you will store the log files for the trail as part of creating the trail in the CloudTrail console.

Note

This tutorial assumes you are creating your first trail. Depending on the number of trails you have in your AWS account, and how those trails are configured, the following procedure might or might not incur expenses. In addition, CloudTrail stores log files in an Amazon S3 bucket. For more information about pricing, see AWS CloudTrail Pricing and Amazon S3 Pricing.

  1. Sign in to the AWS Management Console using the IAM user you configured for CloudTrail administration. Open the CloudTrail console at https://console.aws.amazon.com/cloudtrail/home/. In the Region selector, choose the AWS Region where you want your trail to be created. This is the Home Region for the trail.

    Note

    The Home Region is the only AWS Region where you can view and update the trail after it is created, even if the trail logs events in all AWS Regions.

  2. In the navigation pane, choose Trails. On the Trails page, choose Get Started Now. If you do not see that option, choose Create Trail.

  3. In Trail name, give your trail a name, such as My-Management-Events-Trail. As a best practice, use a name that quickly identifies the purpose of the trail. In this case, you're creating a trail that logs management events.

  4. In Management Events, make sure Read/Write events is set to All.

  5. In Data Events, do not make any changes. This trail will not log any data events.

  6. In Storage Location, in Create a new S3 bucket, choose Yes. In S3 bucket, give your bucket a name, such as my-bucket-for-storing-cloudtrail-logs.

    Note

    The name of your Amazon S3 bucket must be globally unique. For more information, see Amazon S3 Bucket Naming Requirements.

  7. Choose Create.

Step 3: View Your Log Files

Within 15 minutes of creating your first trail, CloudTrail delivers the first set of log files to the Amazon S3 bucket for your trail. You can look at these files and learn about the information they contain.

  1. In the navigation pane, choose Trails. On the Trails page, find the name of the trail you just created (in the example, My-Management-Events-Trail).

    Note

    Make sure you are still signed in using the IAM user you configured for CloudTrail administration. Otherwise you might not have sufficient permissions to view trails in the CloudTrail console or the Amazon S3 bucket that contains log files for that trail.

  2. In the row for that trail, find the value for the S3 bucket (in the example, my-bucket-for-storing-cloudtrail-logs). Choose it.

  3. The Amazon S3 console opens and shows that bucket, at the top level for log files. Because you created a trail that logs events in all AWS Regions, the display opens at the level that shows you each Region folder. The hierarchy of the Amazon S3 bucket navigation at this level is bucket-name/AWSLogs/AWS-account-id/CloudTrail. Choose the folder for the AWS Region where you want to review log files. For example, if you want to review the log files for the US East (Ohio) Region, choose us-east-2.

    
      An Amazon S3 bucket for a trail, showing the structure for log files in AWS Regions
  4. Navigate the bucket folder structure to the year, the month, and the day where you want to review logs of activity in that Region. In that day, there are a number of files. The name of the files begin with your AWS account ID, and end with the extension .gz. For example, if your account ID is 123456789012, you would see files with names similar to this: 123456789012_CloudTrail_us-east-2_20190610T1255abcdeEXAMPLE.json.gz.

    To view these files, you can download them, unzip them, and then view them in a plain-text editor or a JSON file viewer. Some browsers also support viewing .gz and JSON files directly. We recommend using a JSON viewer, as it makes it easier to parse the information in CloudTrail log files.

    As you're browsing through the file content, you might start to wonder about what you're seeing. CloudTrail logs events for every AWS service that experienced activity in that AWS Region at the time that event occurred. In other words, events for different AWS services are mixed together, based solely on time. To learn more about what a specific AWS service logs with CloudTrail, including examples of log file entries for API calls for that service, see the list of supported services for CloudTrail, and read the CloudTrail integration topic for that service. You can also learn more about the content and structure of CloudTrail log files by reviewing the CloudTrail Log Event Reference.

    You might also notice what you're not seeing in log files in US East (Ohio). Specifically, you won't see any console sign-in events, even though you know you logged into the console. That's because console sign-in and IAM events are global service events, and are logged in a specific AWS Region. In this case, they are logged in US East (N. Virginia), which corresponds to the folder us-east-1. Navigate to that folder, and to the year, month, and day you're interested in. Browse the log files, and you find ConsoleLogin events that look similar to the following:

    { "eventVersion": "1.05", "userIdentity": { "type": "IAMUser", "principalId": "AKIAIOSFODNN7EXAMPLE", "arn": "arn:aws:iam::123456789012:user/Mary_Major", "accountId": "123456789012", "userName": "Mary_Major" }, "eventTime": "2019-06-10T17:14:09Z", "eventSource": "signin.amazonaws.com", "eventName": "ConsoleLogin", "awsRegion": "us-east-1", "sourceIPAddress": "203.0.113.67", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0", "requestParameters": null, "responseElements": { "ConsoleLogin": "Success" }, "additionalEventData": { "LoginTo": "https://console.aws.amazon.com/console/home?state=hashArgs%23&isauthcode=true", "MobileVersion": "No", "MFAUsed": "No" }, "eventID": "2681fc29-EXAMPLE", "eventType": "AwsConsoleSignIn", "recipientAccountId": "123456789012" }

    You'll notice that this log file entry tells you more than just the identity of the IAM user who logged in (Mary_Major), the date and time she logged in, and that the login was successful. You can also learn the IP address she logged in from, the operating system and browser software of the computer she used, and that she was not using multi-factor authentication.

Step 4: Plan For Next Steps

Now that you have a trail, you have access to an ongoing record of events and activities in your AWS account. This ongoing record helps you meet accounting and auditing needs for your AWS account. However, there is a lot more you can do with CloudTrail and CloudTrail data.