Developer Guide

Tracing Incoming Requests with the X-Ray SDK for Python Middleware

You can use the X-Ray SDK to trace incoming HTTP requests that your application serves on an EC2 instance in Amazon EC2, AWS Elastic Beanstalk, or Amazon ECS.


If your application runs on AWS Lambda, you can use the Lambda X-Ray integration to trace incoming requests automatically.

Use the Django middleware to instrument incoming HTTP requests. When you add the middleware to your application and configure a segment name, the X-Ray SDK for Python creates a segment for each sampled request. Any segments created by additional instrumentation become subsegments of the request-level segment that provides information about the HTTP request and response. This information includes timing, method, and disposition of the request.

Forwarded Requests

If a load balancer or other intermediary forwards a request to your application, X-Ray takes the client IP from the X-Forwarded-For header in the request instead of from the source IP in the IP packet. The client IP that is recorded for a forwarded request can be forged, so it should not be trusted.

When a request is forwarded, the SDK sets an additional field in the segment to indicate this. If the segment contains the field x_forwarded_for set to true, the client IP was taken from the X-Forwarded-For header in the HTTP request.

The message handler creates a segment for each incoming request with an http block that contains the following information:

  • HTTP method – GET, POST, PUT, DELETE, etc.

  • Client address – The IP address of the client that sent the request.

  • Response code – The HTTP response code for the completed request.

  • Timing – The start time (when the request was received) and end time (when the response was sent).

  • User agent — The user-agent from the request.

  • Content length — The content-length from the response.

Adding the Middleware to Your Django Application

Add the middleware to the MIDDLEWARE list in your file.


The X-Ray middleware should be the first line in your file to to ensure that requests that fail in other middleware are recorded.

Example - X-Ray SDK for Python middleware


Configuring a Segment Name

AWS X-Ray uses a service name to identify your application and distinguish it from other applications, databases, external APIs, and AWS resources that your application uses. When the X-Ray SDK generates segments for incoming requests, it records your application's service name in the segment's name field.

The X-Ray SDK can name segments after the host name in the HTTP request header. However, this header can be forged, which could result in unexpected nodes in your service map. To prevent the SDK from naming segments incorrectly due to requests with forged host headers, you must specify a default name for incoming requests.

Use the configure command to set the segment name.

Example – segment name

from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(service='My app')


You can override the default service name that you define in code with the AWS_XRAY_TRACING_NAME environment variable.

Recorder Configuration

You can use the Django file to configure options on the global recorder:

  • AWS_TRACING_DAEMON_ADDRESS – Set the host and port of the X-Ray daemon listener.

  • AUTO_INSTRUMENT – Record subsegments for built-in database and template rendering operations.

  • AWS_TRACING_CONTEXT_MISSING – Set to LOG_ERROR to avoid throwing exceptions when your instrumented code attempts to record data when no segment is open.

  • PLUGINS – Record information about your application's AWS resources.

  • SAMPLING – Set to False to disable sampling.

  • AWS_XRAY_TRACING_NAME – Set a service name that the SDK uses for segments.

  • SAMPLING_RULES – Set the name of the JSON file containing your sampling rules.

To enable recorder configuration in, add the Django middleware to the list of installed apps.

Example – installed apps


Configure the available settings in a list named XRAY_RECORDER.

Example – installed apps

    'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin', 'ECSPlugin'),
    'SAMPLING': False,
    'AWS_XRAY_TRACING_NAME': 'My application',

These options are also available from the configure method on xray_recorder. The options are the same, except that the names are in snake case. See Configuring a Segment Name for an example.