Logging X-Ray API calls with Amazon CloudTrail - Amazon X-Ray
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.

Logging X-Ray API calls with Amazon CloudTrail

Amazon X-Ray integrates with Amazon CloudTrail to record API actions made by a user, a role, or an Amazon service in X-Ray. You can use CloudTrail to monitor X-Ray API requests in real time and store logs in Amazon S3, Amazon CloudWatch Logs, and Amazon CloudWatch Events. X-Ray supports logging the following actions as events in CloudTrail log files:

To create a trail

  1. Open the Trails page of the CloudTrail console.

  2. Choose Create trail.

  3. Enter a trail name, and then choose the types of event to record.

    • Management events – Record API actions that create, read, update, or delete Amazon resources. Records calls to all supported API actions for all Amazon services.

    • Data events – Record API actions that target specific resources, like Amazon S3 object reads or Amazon Lambda function invocations. You choose which buckets and functions to monitor.

  4. Choose an Amazon S3 bucket and encryption settings.

  5. Choose Create.

CloudTrail records API calls of the types you chose to log files in Amazon S3. A CloudTrail log is an unordered array of events in JSON format. For each call to a supported API action, CloudTrail records information about the request and the entity that made it. Log events include the action name, parameters, the response from X-Ray, and details about the requester.

Example X-Ray GetEncryptionConfig log entry

{ "eventVersion"=>"1.05", "userIdentity"=>{ "type"=>"AssumedRole", "principalId"=>"AROAJVHBZWD3DN6CI2MHM:MyName", "arn"=>"arn:aws:sts::123456789012:assumed-role/MyRole/MyName", "accountId"=>"123456789012", "accessKeyId"=>"AKIAIOSFODNN7EXAMPLE", "sessionContext"=>{ "attributes"=>{ "mfaAuthenticated"=>"false", "creationDate"=>"2018-9-01T00:24:36Z" }, "sessionIssuer"=>{ "type"=>"Role", "principalId"=>"AROAJVHBZWD3DN6CI2MHM", "arn"=>"arn:aws:iam::123456789012:role/MyRole", "accountId"=>"123456789012", "userName"=>"MyRole" } } }, "eventTime"=>"2018-9-01T00:24:36Z", "eventSource"=>"xray.amazonaws.com", "eventName"=>"GetEncryptionConfig", "awsRegion"=>"us-east-2", "sourceIPAddress"=>"", "userAgent"=>"aws-sdk-ruby2/2.11.19 ruby/2.3.1 x86_64-linux", "requestParameters"=>nil, "responseElements"=>nil, "requestID"=>"3fda699a-32e7-4c20-37af-edc2be5acbdb", "eventID"=>"039c3d45-6baa-11e3-2f3e-e5a036343c9f", "eventType"=>"AwsApiCall", "recipientAccountId"=>"123456789012" }

The userIdentity element contains information about who generated the request. The identity information helps you determine the following:

  • Whether the request was made with root or IAM user credentials.

  • Whether the request was made with temporary security credentials for a role or federated user.

  • Whether the request was made by another Amazon service.

To be notified when a new log file is available, configure CloudTrail to publish Amazon SNS notifications. For more information, see Configuring Amazon SNS Notifications for CloudTrail.

You can also aggregate X-Ray log files from multiple Amazon Regions and multiple Amazon accounts into a single Amazon S3 bucket. For more information, see Receiving CloudTrail Log Files from Multiple Regions and Receiving CloudTrail Log Files from Multiple Accounts.