Homepage
AWS Lambda Powertools for TypeScript provides a suite of utilities for AWS Lambda functions running on the Node.js runtime, to ease the adoption of best practices such as tracing, structured logging, custom metrics, and more.
You can use the library in both TypeScript and JavaScript code bases.
Tenets¶
Core utilities such as Tracer, Logger, Metrics, and Event Handler will be available across all Lambda Powertools runtimes. Additional utilities are subjective to each language ecosystem and customer demand.
- AWS Lambda only. We optimise for AWS Lambda function environments and supported runtimes only. Utilities might work with web frameworks and non-Lambda environments, though they are not officially supported.
- Eases the adoption of best practices. The main priority of the utilities is to facilitate best practices adoption, as defined in the AWS Well-Architected Serverless Lens; all other functionality is optional.
- Keep it lean. Additional dependencies are carefully considered for security and ease of maintenance, and prevent negatively impacting startup time.
- We strive for backwards compatibility. New features and changes should keep backwards compatibility. If a breaking change cannot be avoided, the deprecation and migration process should be clearly defined.
- We work backwards from the community. We aim to strike a balance of what would work best for 80% of customers. Emerging practices are considered and discussed via Requests for Comment (RFCs)
- Progressive. Utilities are designed to be incrementally adoptable for customers at any stage of their Serverless journey. They follow language idioms and their community’s common practices.
Features¶
| Utility | Description |
|---|---|
| Tracer | Trace Lambda function handlers, and both synchronous and asynchronous functions |
| Logger | Structured logging made easier, and a middleware to enrich log items with key details of the Lambda context |
| Metrics | Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF) |
Installation¶
The AWS Lambda Powertools for TypeScript utilities (which from here will be referred as Powertools) follow a modular approach, similar to the official AWS SDK v3 for JavaScript. Each TypeScript utility is installed as standalone NPM package.
Install all three core utilities at once with this single command:
1 | |
Or refer to the installation guide of each utility:
Installation guide for the Tracer utility
Installation guide for the Logger utility
Installation guide for the Metrics utility
Instrumentation¶
You can instrument your code with Powertools in three different ways:
- Middy middleware. It is the best choice if your existing code base relies on the Middy middleware engine. Powertools offers compatible Middy middleware to make this integration seamless.
- Method decorator. Use TypeScript method decorators if you prefer writing your business logic using TypeScript Classes. If you aren’t using Classes, this requires the most significant refactoring.
- Manually. It provides the most granular control. It’s the most verbose approach, with the added benefit of no additional dependency and no refactoring to TypeScript Classes.
The examples in this documentation will feature all the approaches described above, when applicable.
Environment variables¶
Info
Explicit parameters passed in constructors or in middleware/decorators take precedence over environment variables.
| Environment variable | Description | Utility | Default |
|---|---|---|---|
| POWERTOOLS_SERVICE_NAME | Sets service name used for tracing namespace, metrics dimension and structured logging | All | "service_undefined" |
| POWERTOOLS_METRICS_NAMESPACE | Sets namespace used for metrics | Metrics | None |
| POWERTOOLS_TRACE_ENABLED | Explicitly disables tracing | Tracer | true |
| POWERTOOLS_TRACER_CAPTURE_RESPONSE | Captures Lambda or method return as metadata. | Tracer | true |
| POWERTOOLS_TRACER_CAPTURE_ERROR | Captures Lambda or method exception as metadata. | Tracer | true |
| POWERTOOLS_TRACER_CAPTURE_HTTPS_REQUESTS | Captures HTTP(s) requests as segments. | Tracer | true |
| POWERTOOLS_LOGGER_LOG_EVENT | Logs incoming event | Logger | false |
| POWERTOOLS_LOGGER_SAMPLE_RATE | Debug log sampling | Logger | 0 |
| LOG_LEVEL | Sets logging level | Logger | INFO |
Examples¶
Serverless TypeScript demo application¶
The Serverless TypeScript Demo shows how to use Lambda Powertools for TypeScript.
You can find instructions on how to deploy and load test this application in the repository.
Contribute¶
If you are interested in contributing to this project, please refer to our Contributing Guidelines.
Roadmap¶
The roadmap of Powertools is driven by customers’ demand.
Help us prioritize upcoming functionalities or utilities by upvoting existing RFCs and feature requests, or creating new ones, in this GitHub repository.
Connect¶
- AWS Lambda Powertools on Discord:
#typescript- Invite link - Email: aws-lambda-powertools-feedback@amazon.com
Credits¶
Credits for the Lambda Powertools idea go to DAZN and their DAZN Lambda Powertools.
License¶
This library is licensed under the MIT-0 License. See the LICENSE file.