AWS Lambda
Developer Guide

Setting Up AWS X-Ray with Lambda

Following, you can find detailed information on how to set up X-Ray with Lambda.

Before You Begin

To enable tracing on your Lambda function using the Lambda CLI, you must first add tracing permissions to your function's execution role. To do so, take the following steps:

  • Sign in to the AWS Management Console and open the IAM console at

  • Find the execution role for your Lambda function.

  • Attach the following managed policy: AWSXrayWriteOnlyAccess

To learn more about these policies, see AWS X-Ray.

If you are changing the tracing mode to active using the Lambda console, tracing permissions are added automatically, as explained in the next section.


The path of a request through your application is tracked with a trace ID. A trace collects all of the segments generated by a single request, typically an HTTP GET or POST request.

There are two modes of tracing for a Lambda function:

  • Pass Through: This is the default setting for all Lambda functions if you have added tracing permissions to your function's execution role. This approach means the Lambda function is only traced if X-Ray has been enabled on an upstream service, such as AWS Elastic Beanstalk.

  • Active: When a Lambda function has this setting, Lambda automatically samples invocation requests, based on the sampling algorithm specified by X-Ray.


    X-Ray applies a sampling algorithm to ensure that tracing is efficient, while still providing a representative sample of the requests that your application serves. The default sampling algorithm is 1 request per minute, with 5 percent of requests sampled past that limit. However, if the traffic volume to your function is low, you may see an increased rate of sampling.

You can change the tracing mode for your Lambda function by using either the Lambda Management Console or the Lambda CreateFunction or UpdateFunctionConfiguration API actions.

If you use the Lambda console, the following applies:

  • When you change a function's tracing mode to active, tracing permissions are automatically attached to the function's execution role. If you receive an error stating Lambda couldn't add the AWSXrayWriteOnlyAccess policy to your function's execution role, sign in to the IAM console at and manually add the policy.

  • To enable active tracing, go to the Configuration tab your function and select the Enable active tracing box.

If you use the Lambda CreateFunction or UpdateFunctionConfiguration API actions:

  • If you want the tracing mode to be active, set the TracingConfig parameter's Mode property to Active. Again, any new function has its tracing mode set to PassThrough by default.

  • Any new or updated Lambda function has its $LATEST version set to the value you specify.


    You receive an error if you haven't added tracing permissions to your function's execution role. For more information, see Before You Begin.

On this page: