Tracer
Tracer is an opinionated thin wrapper for AWS X-Ray Python SDK.
Key features¶
- Auto capture cold start as annotation, and responses or full exceptions as metadata
- Run functions locally with SAM CLI without code change to disable tracing
- Explicitly disable tracing via env var
POWERTOOLS_TRACE_DISABLED="true"
- Support tracing async methods, generators, and context managers
- Auto patch supported modules by AWS X-Ray
Getting started¶
Permissions¶
Before your use this utility, your AWS Lambda function must have permissions to send traces to AWS X-Ray.
Example using AWS Serverless Application Model (SAM)
1 2 3 4 5 6 7 8 9 |
|
Lambda handler¶
You can quickly start by importing the Tracer
class, initialize it outside the Lambda handler, and use capture_lambda_handler
decorator.
1 2 3 4 5 6 7 8 9 10 |
|
When using this capture_lambda_handler
decorator, Tracer performs these additional tasks to ease operations:
- Creates a
ColdStart
annotation to easily filter traces that have had an initialization overhead - Captures any response, or full exceptions generated by the handler, and include as tracing metadata
Annotations & Metadata¶
Annotations are key-values associated with traces and indexed by AWS X-Ray. You can use them to filter traces and to create Trace Groups to slice and dice your transactions.
Metadata are key-values also associated with traces but not indexed by AWS X-Ray. You can use them to add additional context for an operation using any native object.
You can add annotations using put_annotation
method.
1 2 3 4 5 6 7 |
|
You can add metadata using put_metadata
method.
1 2 3 4 5 6 7 8 |
|
Synchronous functions¶
You can trace synchronous functions using the capture_method
decorator.
Warning
When capture_response
is enabled, the function response will be read and serialized as json.
The serialization is performed by the aws-xray-sdk which uses the jsonpickle
module. This can cause
unintended consequences if there are side effects to recursively reading the returned value, for example if the
decorated function response contains a file-like object or a StreamingBody
for S3 objects.
1 2 3 4 5 |
|
Asynchronous and generator functions¶
Warning
We do not support async Lambda handler - Lambda handler itself must be synchronous
You can trace asynchronous functions and generator functions (including context managers) using capture_method
.
1 2 3 4 5 6 7 8 9 |
|
1 2 3 4 5 6 7 8 9 10 11 |
|
1 2 3 4 5 6 7 8 9 10 |
|
The decorator will detect whether your function is asynchronous, a generator, or a context manager and adapt its behaviour accordingly.
1 2 3 4 5 6 7 8 |
|
Advanced¶
Patching modules¶
Tracer automatically patches all supported libraries by X-Ray during initialization, by default. Underneath, AWS X-Ray SDK checks whether a supported library has been imported before patching.
If you're looking to shave a few microseconds, or milliseconds depending on your function memory configuration, you can patch specific modules using patch_modules
param:
1 2 3 4 5 6 7 |
|
Disabling response auto-capture¶
New in 1.9.0
Use capture_response=False
parameter in both capture_lambda_handler
and capture_method
decorators to instruct Tracer not to serialize function responses as metadata.
This is commonly useful in two scenarios
- You might return sensitive information you don't want it to be added to your traces
- You might manipulate streaming objects that can be read only once; this prevents subsequent calls from being empty
1 2 3 4 5 6 7 8 9 |
|
1 2 3 4 5 6 7 |
|
Disabling exception auto-capture¶
New in 1.10.0
Use capture_error=False
parameter in both capture_lambda_handler
and capture_method
decorators to instruct Tracer not to serialize exceptions as metadata.
Commonly useful in one scenario
- You might return sensitive information from exceptions, stack traces you might not control
1 2 3 4 5 |
|
Tracing aiohttp requests¶
Info
This snippet assumes you have aiohttp as a dependency
You can use aiohttp_trace_config
function to create a valid aiohttp trace_config object. This is necessary since X-Ray utilizes aiohttp trace hooks to capture requests end-to-end.
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
Escape hatch mechanism¶
You can use tracer.provider
attribute to access all methods provided by AWS X-Ray xray_recorder
object.
This is useful when you need a feature available in X-Ray that is not available in the Tracer utility, for example thread-safe, or context managers.
1 2 3 4 5 6 7 8 9 |
|
Concurrent asynchronous functions¶
Warning
As of now, X-Ray SDK will raise an exception when async functions are run and traced concurrently
A safe workaround mechanism is to use in_subsegment_async
available via Tracer escape hatch (tracer.provider
).
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
Reusing Tracer across your code¶
Tracer keeps a copy of its configuration after the first initialization. This is useful for scenarios where you want to use Tracer in more than one location across your code base.
Warning
When reusing Tracer in Lambda Layers, or in multiple modules, do not set auto_patch=False
, because import order matters.
This can result in the first Tracer config being inherited by new instances, and their modules not being patched.
1 2 3 4 5 6 7 8 9 |
|
A new instance of Tracer will be created but will reuse the previous Tracer instance configuration, similar to a Singleton.
1 2 3 4 5 6 7 |
|
Testing your code¶
You can safely disable Tracer when unit testing your code using POWERTOOLS_TRACE_DISABLED
environment variable.
1 |
|
Tips¶
- Use annotations on key operations to slice and dice traces, create unique views, and create metrics from it via Trace Groups
- Use a namespace when adding metadata to group data more easily
- Annotations and metadata are added to the current subsegment opened. If you want them in a specific subsegment, use a context manager via the escape hatch mechanism