Instrumenting web frameworks deployed to serverless environments - 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 (PDF).

Instrumenting web frameworks deployed to serverless environments

The Amazon X-Ray SDK for Python supports instrumenting web frameworks deployed in serverless applications. Serverless is the native architecture of the cloud that enables you to shift more of your operational responsibilities to Amazon, increasing your agility and innovation.

Serverless architecture is a software application model that enables you to build and run applications and services without thinking about servers. It eliminates infrastructure management tasks such as server or cluster provisioning, patching, operating system maintenance, and capacity provisioning. You can build serverless solutions for nearly any type of application or backend service, and everything required to run and scale your application with high availability is handled for you.

This tutorial shows you how to automatically instrument Amazon X-Ray on a web framework, such as Flask or Django, that is deployed to a serverless environment. X-Ray instrumentation of the application enables you to view all downstream calls that are made, starting from Amazon API Gateway through your Amazon Lambda function, and the outgoing calls your application makes.

The X-Ray SDK for Python supports the following Python application frameworks:

  • Flask version 0.8, or later

  • Django version 1.0, or later

This tutorial develops an example serverless application that is deployed to Lambda and invoked by API Gateway. This tutorial uses Zappa to automatically deploy the application to Lambda and to configure the API Gateway endpoint.


  • Zappa

  • Python – Version 2.7 or 3.6.

  • Amazon CLI – Verify that your Amazon CLI is configured with the account and Amazon Web Services Region in which you will deploy your application.

  • Pip

  • Virtualenv

Step 1: Create an environment

In this step, you create a virtual environment using virtualenv to host an application.

  1. Using the Amazon CLI, create a directory for the application. Then change to the new directory.

    mkdir serverless_application cd serverless_application
  2. Next, create a virtual environment within your new directory. Use the following command to activate it.

    # Create our virtual environment virtualenv serverless_env # Activate it source serverless_env/bin/activate
  3. Install X-Ray, Flask, Zappa, and the Requests library to your environment.

    # Install X-Ray, Flask, Zappa, and Requests into your environment pip install aws-xray-sdk flask zappa requests
  4. Add application code to the serverless_application directory. For this example, we can build off of Flasks's Hello World example.

    In the serverless_application directory, create a file named Then use a text editor to add the following commands. This application instruments the Requests library, patches the Flask application's middleware, and opens the endpoint '/'.

    # Import the X-Ray modules from aws_xray_sdk.ext.flask.middleware import XRayMiddleware from aws_xray_sdk.core import patcher, xray_recorder from flask import Flask import requests # Patch the requests module to enable automatic instrumentation patcher.patch(('requests',)) app = Flask(__name__) # Configure the X-Ray recorder to generate segments with our service name xray_recorder.configure(service='My First Serverless App') # Instrument the Flask application XRayMiddleware(app, xray_recorder) @app.route('/') def hello_world(): resp = requests.get("") return 'Hello, World: %s' % resp.url

Step 2: Create and deploy a zappa environment

In this step you will use Zappa to automatically configure an API Gateway endpoint and then deploy to Lambda.

  1. Initialize Zappa from within the serverless_application directory. For this example, we used the default settings, but if you have customization preferences, Zappa displays configuration instructions.

    zappa init
    What do you want to call this environment (default 'dev'): dev
    What do you want to call your bucket? (default 'zappa-*******'): zappa-*******
    It looks like this is a Flask application.
    What's the modular path to your app's function?
    This will likely be something like ''.
    We discovered:
    Where is your app's function? (default ''):
    Would you like to deploy this application globally? (default 'n') [y/n/(p)rimary]: n
  2. Enable X-Ray. Open the zappa_settings.json file and verify that it looks similar to the example.

    { "dev": { "app_function": "", "aws_region": "us-west-2", "profile_name": "default", "project_name": "serverless-exam", "runtime": "python2.7", "s3_bucket": "zappa-*********" } }
  3. Add "xray_tracing": true as an entry to the configuration file.

    { "dev": { "app_function": "", "aws_region": "us-west-2", "profile_name": "default", "project_name": "serverless-exam", "runtime": "python2.7", "s3_bucket": "zappa-*********", "xray_tracing": true } }
  4. Deploy the application. This automatically configures the API Gateway endpoint and uploads your code to Lambda.

    zappa deploy
    Deploying API Gateway..
    Deployment complete!: https://**********

Step 3: Enable X-Ray tracing for API Gateway

In this step you will interact with the API Gateway console to enable X-Ray tracing.

  1. Sign in to the Amazon Web Services Management Console and open the API Gateway console at

  2. Find your newly generated API. It should look something like serverless-exam-dev.

  3. Choose Stages.

  4. Choose the name of your deployment stage. The default is dev.

  5. On the Logs/Tracing tab, select the Enable X-Ray Tracing box.

  6. Choose Save Changes.

  7. Access the endpoint in your browser. If you used the example Hello World application, it should display the following.

    "Hello, World:"

Step 4: View the created trace

In this step you will interact with the X-Ray console to view the trace created by the example application. For a more detailed walkthrough on trace analysis, see Viewing the Service Map.

  1. Sign in to the Amazon Web Services Management Console and open the X-Ray console at

  2. View segments generated by API Gateway, the Lambda function, and the Lambda container.

  3. Under the Lambda function segment, view a subsegment named My First Serverless App. It's followed by a second subsegment named

  4. During initialization, Lambda might also generate a third subsegment named initialization.

Trace segment view.
Service graph view.

Step 5: Clean up

Always terminate resources you are no longer using to avoid the accumulation of unexpected costs. As this tutorial demonstrates, tools such as Zappa streamline serverless redeployment.

To remove your application from Lambda, API Gateway, and Amazon S3, run the following command in your project directory by using the Amazon CLI.

zappa undeploy dev

Next steps

Add more features to your application by adding Amazon clients and instrumenting them with X-Ray. Learn more about serverless computing options at Serverless on Amazon.