Django¶
Configure X-Ray Recorder¶
Make sure you add XRayMiddleWare
as the first entry in your
Django settings.py file, as shown in the following example:
MIDDLEWARE = [
'aws_xray_sdk.ext.django.middleware.XRayMiddleware',
'django.contrib.auth.middleware.AuthenticationMiddleware',
'django.contrib.messages.middleware.MessageMiddleware',
]
The incoming requests to the Django app are then automatically recorded as a segment.
To get the current segment and add annotations or metadata as needed, use the following statement in your application code when processing request:
segment = xray_recorder.current_segment()
For more configurations in your Django settings.py
file,
add the following line:
INSTALLED_APPS = [
'django.contrib.admin',
...
'django.contrib.sessions',
'aws_xray_sdk.ext.django',
]
You can configure the X-Ray recorder in a Django app under the ‘XRAY_RECORDER’ namespace. The default values are as follows:
XRAY_RECORDER = {
'AWS_XRAY_DAEMON_ADDRESS': '127.0.0.1:2000',
'AUTO_INSTRUMENT': True, # If turned on built-in database queries and template rendering will be recorded as subsegments
'AWS_XRAY_CONTEXT_MISSING': 'LOG_ERROR',
'PLUGINS': (),
'SAMPLING': True,
'SAMPLING_RULES': None,
'AWS_XRAY_TRACING_NAME': None, # the segment name for segments generated from incoming requests
'DYNAMIC_NAMING': None, # defines a pattern that host names should match
'STREAMING_THRESHOLD': None, # defines when a segment starts to stream out its children subsegments
}
Environment variables have higher precedence over user settings. If neither is set, the defaults values shown previously are used. ‘AWS_XRAY_TRACING_NAME’ is required unless specified as an environment variable. All other keys are optional. For further information on individual settings, see the Configure Global Recorder section.
Local Development¶
When doing Django app local development, if you configured Django built-in database with AUTO_INSTRUMENT
turned-on,
the command manage.py runserver
may fail if AWS_XRAY_CONTEXT_MISSING
is set to RUNTIME_ERROR
. This is because
the command runserver
performs migrations check which will generate a subsegment,
the xray_recorder
will raise an error since there is no active segment.
One solution is to set AWS_XRAY_CONTEXT_MISSING
to LOG_ERROR
so it only emits a error message on server startup.
Alternatively if you have defined your own ready()
function for code execution at startup you can manually create a segment
as a placeholder.
By Django official guide it’s recommanded to deploy Django to other servers in production so this particular issue normally doesn’t exist in production.
Flask¶
To generate segment based on incoming requests, you need to instantiate the X-Ray middleware for flask:
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.ext.flask.middleware import XRayMiddleware
app = Flask(__name__)
xray_recorder.configure(service='my_app_name')
XRayMiddleware(app, xray_recorder)
Flask built-in template rendering will be wrapped into subsegments. You can configure the recorder, see Configure Global Recorder for more details.
Aiohttp¶
Server¶
For X-Ray to create a segment based on an incoming request, you need register some middleware with aiohttp. As aiohttp
is an asyncronous framework, X-Ray will also need to be configured with an AsyncContext
compared to the default threaded
version.:
import asyncio
from aiohttp import web
from aws_xray_sdk.ext.aiohttp.middleware import middleware
from aws_xray_sdk.core.async_context import AsyncContext
from aws_xray_sdk.core import xray_recorder
# Configure X-Ray to use AsyncContext
xray_recorder.configure(service='service_name', context=AsyncContext())
async def handler(request):
return web.Response(body='Hello World')
loop = asyncio.get_event_loop()
# Use X-Ray SDK middleware, its crucial the X-Ray middleware comes first
app = web.Application(middlewares=[middleware])
app.router.add_get("/", handler)
web.run_app(app)
There are two things to note from the example above. Firstly a middleware corountine from aws-xray-sdk is provided during the creation
of an aiohttp server app. Lastly the xray_recorder
has also been configured with a name and an AsyncContext
. See
Configure Global Recorder for more information about configuring the xray_recorder
.
Client¶
Since 3.0.0 Aiohttp provides a generic object that allows third packages to gather the different events ocurred during an HTTP call, X-Ray can be configured to track these requests as subsegments using the aws_xray_trace_config function. This will return a valid TraceConfig ready to be installed in any aiohttp.ClientSession. The following example shows how it can be used.:
from aws_xray_sdk.ext.aiohttp.client import aws_xray_trace_config
trace_config = aws_xray_trace_config()
async with ClientSession(loop=loop, trace_configs=[trace_config]) as session:
async with session.get(url) as resp
await resp.read()