Skip to main content
This guide shows how to enable AWS X-Ray tracing for an AWS Lambda function so you can collect traces, analyze latency, and investigate errors or performance issues. Follow the steps in order: create the Lambda, enable tracing, invoke the function to generate traces, then inspect those traces and related logs in the X-Ray console. What you’ll accomplish
  • Create a simple Lambda function (Python runtime) named xray-demo.
  • Enable Lambda service tracing so the function can send traces to X-Ray.
  • Invoke the function with test events to generate traces.
  • Inspect traces, metrics, and logs in the X-Ray console.

Quick summary of steps

1. Create the Lambda function

  1. In the AWS Lambda console choose Create function.
  2. Select Author from scratch, name the function xray-demo, choose a Python runtime (for example Python 3.9), and accept the defaults.
  3. Create the function and wait for the function configuration page to load.
A screenshot of the AWS Management Console on the AWS Lambda "Functions" page, showing a single function named "ec2-event-handler" in the functions list and an orange "Create function" button. The left sidebar displays Lambda navigation items like Dashboard and Function resources.

2. Enable X‑Ray tracing for the function

  1. On the xray-demo function page open the Configuration tab.
  2. Scroll to Monitoring and Operations Tools and click Edit.
  3. Under Additional monitoring tools enable Lambda service traces (optionally enable Application Signals), then click Save.
A screenshot of the AWS Lambda console showing the "CloudWatch Application Signals and AWS X‑Ray" monitoring settings. It displays options to enable Application Signals and Lambda service traces and lists supported runtimes.
Enabling tracing from the Lambda console will automatically update the function’s execution role to include permissions required to send trace data to X‑Ray. If your role is immutable or restricted (for example, due to permission boundaries), attach the AWS managed policy AWSXRayDaemonWriteAccess (or an equivalent policy) to the function’s execution role manually.

3. Create a test event and invoke the function

  1. Open the Test tab for the Lambda function.
  2. Create a new test event (for example name it X-Ray test) and use a simple JSON payload. The default sample event works fine:
  1. Save the test event and invoke the function multiple times to generate trace data. Each invocation returns a response and basic console log similar to:
A screenshot of the AWS Lambda console for a function (xray-demo) showing the Invocation type options with "Synchronous" selected and an Event name input partially filled ("XR"), plus event sharing settings.

4. Open the X‑Ray console and inspect traces

  1. Open CloudWatch X‑Ray in a new browser tab and allow it to load.
  2. Switch between the Map and List views:
    • Map view visualizes services and request flow between them.
    • List view shows individual trace segments and allows you to open detailed trace records.
Note: Traces typically appear within a minute of invocation.
A screenshot of the AWS CloudWatch X-Ray Trace Map page showing two nodes named "xray-demo" (Lambda Context and Lambda Function) with columns for latency, faults (5xx), and request rates.

5. Review metrics and traced requests

Use the metrics panels to inspect latency, request rates, and faults over time. These metrics give you a high‑level view before you drill into individual traces.
A screenshot of the AWS CloudWatch Trace Map metrics page showing three panels: Latency, Requests, and Faults (5xx) with small line graphs over time. The header shows metrics like average latency ~2 ms, requests ~1.60/min, and faults 0.00/min.

6. View the traces list

The Traces table lists individual trace IDs, timestamps, HTTP/status codes, and durations. Each entry corresponds to a Lambda invocation you performed earlier.
Screenshot of the AWS CloudWatch "Traces" console showing a table of recent trace IDs with green OK status, timestamps, 200 response codes, and short response times (around 0.01–0.02s).

7. Select an individual trace to see details

Opening a trace shows a detailed view with segments for the Lambda service and the function invocation, response codes, durations, and any annotations or metadata. From here you can jump to related logs. Example trace segment selector:
Screenshot of an AWS CloudWatch X‑Ray trace details page showing "xray-demo" Lambda and Lambda::Function segments with green OK status icons, a 200 response code, and durations like 13ms, 1ms and 0ms.

8. View logs associated with a trace

X‑Ray includes a Logs section that links to CloudWatch Logs for the trace. Typical Lambda log entries look like:
You can filter or query services using expressions such as:

Troubleshooting and tips

If you don’t see traces after invoking the function:
  • Confirm that Lambda service traces is enabled in the function configuration.
  • Verify the function’s execution role has AWSXRayDaemonWriteAccess (or equivalent) permissions.
  • Wait a minute; traces can take a short time to appear in X‑Ray.

Conclusion

After enabling X‑Ray traces and invoking xray-demo a few times, traces will appear in the X‑Ray console. Use the Map and List views to analyze request flows, detect latency hotspots, and identify errors. From a trace you can jump directly to logs for deeper investigation. For richer, in‑code tracing (custom subsegments, annotations, and metadata), instrument your Lambda function using the AWS X‑Ray SDK and follow the AWS X‑Ray Developer Guide:

Watch Video

Practice Lab