Using AWS X-Ray for debugging AWS Lambda Functions

AWS Lambda is a serverless computing service that lets you run code without provisioning or managing servers. AWS X-Ray provides insights into the behavior of your applications, helping you understand how they are performing and where bottlenecks are occurring. AWS X-Ray provides a complete view of requests as they travel through your application and filters visual data across payloads, functions, traces, services, APIs, and more with no-code and low-code motions.

Use Cases:

  1. Performance Analysis: Track and analyze the execution of your Lambda function to identify performance bottlenecks.

  2. Error Tracing: Understand and troubleshoot issues when errors occur in your Lambda function.

  3. Visualization: See a visual representation of how your Lambda function interacts with other AWS resources.

  4. Monitoring and Alerting: Integrate with AWS CloudWatch to monitor the traces and set up alerts based on the metrics.

Tutorial: Integrating AWS X-Ray with AWS Lambda function

To use the X-Ray SDK on Lambda, bundle it with your function code each time you create a new version. You can instrument your Lambda functions with the same methods that you use to instrument applications running on other services. The primary difference is that you don't use the SDK to instrument incoming requests, make sampling decisions, and create segments.

The other difference between instrumenting Lambda functions and web applications is that the segment that Lambda creates and sends to X-Ray can't be modified by your function code. You can create subsegments and record annotations and metadata on them, but you can't add annotations and metadata to the parent segment.

For more information, see Using AWS X-Ray in the AWS Lambda Developer Guide.

1. Setting up IAM permissions:

Before you can use X-Ray with Lambda, ensure that the Lambda function has the necessary IAM permissions.

To set up example Lambda functions use one provided in the following guide: How to use an Amazon S3 trigger to invoke a Lambda function. Code files are available at
  • Go to the IAM Console and find the role associated with your Lambda function.

  • Attach the AWSXRayDaemonWriteAccess managed policy to this role.

2. Enable X-Ray Tracing in Lambda:

  • Open the AWS Lambda Console.

  • Select the Lambda function you want to enable X-Ray for.

  • In the "Designer" section, click on the function name.

  • In the "Function overview" pane below, under "Configuration" tab find the "Monitoring and operations tools" section and click on "Edit".

  • Check the "Enable active tracing" checkbox to enable AWS X-Ray.

  • Click "Save".

3. Install required packages and X-Ray SDK:

To install required libraries and X-Ray SDK use the following command:

  pip install \
  --platform manylinux2014_x86_64 \
  --target=package \
  --implementation cp \
  --python-version 3.8 \
  --only-binary=:all: --upgrade \
  pillow boto3 aws-xray-sdk

4. Modify Lambda code to use the X-Ray SDK:

You'll need to make some changes to your Lambda function code to make use of the X-Ray SDK.

For Python:

import boto3
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all

# This will instrument libraries supported by the X-Ray SDK

def lambda_handler(event, context):
    s3 = boto3.client('s3')
    # your code here

The patch_all() function is commonly used in the context of the AWS X-Ray SDK, especially when instrumenting Python applications to send trace data to AWS X-Ray.

Remember, if you're deploying a Lambda function, you'll need to include the AWS X-Ray SDK in your deployment package.

5. Execute the Lambda function:

Invoke your Lambda function. If it's triggered by events like S3 or DynamoDB, perform an action that would trigger the function. Otherwise, you can manually invoke it from the AWS Console or the AWS CLI.

6. View Traces in the X-Ray Console:

  • Open the AWS X-Ray Console.

  • In the "Service map" section, you can see a visual representation of your Lambda function and the services it interacts with.

  • Click on "Traces" in the menu to view traces that represent the execution of your function and the calls it made to other services.

7. Analyze Trace Details:

You can dive into individual traces to see:

  • How long each segment took.

  • Which calls or operations were slow.

  • Any errors or exceptions that occurred.

By doing so, you can gain deep insights into the performance of your Lambda function and the services it interacts with.

Note: Always ensure to be cautious when instrumenting your code, especially in a production environment. Too much detailed tracing can introduce overhead. Always test thoroughly to understand the impact.

Integration of AWS Lambda with AWS X-Ray provides you with deep insights and visualizations about your serverless applications. By using them together, you can optimize performance, troubleshoot errors, and understand the flow of requests within your application.


  1. AWS Lambda and AWS X-Ray

  2. Using AWS Lambda with AWS X-Ray

  3. How to use an Amazon S3 trigger to invoke a Lambda function