Do not use this library in production
AWS Lambda Powertools for TypeScript is currently released as a beta developer preview and is intended strictly for feedback purposes only.
This version is not stable, and significant breaking changes might incur as part of the upcoming production-ready release.
Do not use this library for production workloads.
Tracer is an opinionated thin wrapper for AWS X-Ray SDK for Node.js.
- Auto capture cold start and service name as annotations, and responses or full exceptions as metadata
- Auto-disable when not running in AWS Lambda environment
- Support tracing functions via decorators, middleware, and manual instrumentation
- Support tracing AWS SDK v2 and v3 via AWS X-Ray SDK for Node.js
Install the library in your project:
The library has one optional setting. You can set it as environment variable, or pass it in the constructor.
This setting will be used across all traces emitted:
|Setting||Description||Environment variable||Constructor parameter|
|Service name||Sets an annotation with the name of the service across all traces e.g.
For a complete list of supported environment variables, refer to this section.
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
1 2 3 4 5 6 7 8 9
You can quickly start by importing the
Tracer class, initialize it outside the Lambda handler, and instrument your function.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
Middy comes bundled with Tracer, so you can just import it when using the middleware.
Using Middy for the first time?
Learn more about its usage and lifecycle in the official Middy documentation.
1 2 3 4 5 6 7 8 9 10 11 12 13
Decorators can only be attached to a class declaration, method, accessor, property, or parameter. Therefore, if you prefer to write your handler as a standard function rather than a Class method, use the middleware or the manual instrumentations instead.
See the official TypeScript documentation for more details.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
When using the
captureLambdaHandler decorator or middleware, Tracer performs these additional tasks to ease operations:
- Handles the lifecycle of the subsegment
- Creates a
ColdStartannotation to easily filter traces that have had an initialization overhead
- Creates a
Serviceannotation to easily filter traces that have a specific service name
- Captures any response, or full exceptions generated by the handler, and include them 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
1 2 3 4 5 6 7
You can add metadata using
1 2 3 4 5 6 7 8
You can trace other Class methods using the
captureMethod decorator or any arbitrary function using manual instrumentation.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
Patching AWS SDK clients¶
Tracer can patch any AWS SDK clients and create traces when your application makes calls to AWS services.
You can patch any AWS SDK clients by calling the
1 2 3 4 5
You can patch all AWS SDK v2 clients by calling the
1 2 3 4
If you're looking to shave a few microseconds, or milliseconds depending on your function memory configuration, you can patch only specific AWS SDK v2 clients using
1 2 3 4 5
Disabling response auto-capture¶
POWERTOOLS_TRACER_CAPTURE_RESPONSE=false environment variable to instruct Tracer not to serialize function responses as metadata.
This is commonly useful in three 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
- You might return more than 64K of data e.g.,
message too longerror
Disabling exception auto-capture¶
POWERTOOLS_TRACER_CAPTURE_ERROR=false environment variable 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
Escape hatch mechanism¶
You can use
tracer.provider attribute to access all methods provided by the AWS X-Ray SDK.
1 2 3 4 5 6 7
Testing your code¶
Tracer is disabled by default when not running in the AWS Lambda environment - This means no code changes or environment variables to be set.
- 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, create one via the escape hatch mechanism