From c25279cee6a8e6762451afb06485e446f13718fe Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Tue, 25 Oct 2022 13:09:34 +0200 Subject: [PATCH] docs: main page updates around support (#1133) * docs: main page updates around support * Update docs/index.md Co-authored-by: Heitor Lessa Co-authored-by: Heitor Lessa --- docs/core/logger.md | 12 +- docs/core/metrics.md | 6 +- docs/core/tracer.md | 20 +- docs/index.md | 441 +++++++++++++++++++------------------------ 4 files changed, 215 insertions(+), 264 deletions(-) diff --git a/docs/core/logger.md b/docs/core/logger.md index 20d32f3d57..ab0bd44986 100644 --- a/docs/core/logger.md +++ b/docs/core/logger.md @@ -52,12 +52,12 @@ The library requires two settings. You can set them as environment variables, or These settings will be used across all logs emitted: -| Setting | Description | Environment variable | Constructor parameter | -|-------------------|------------------------------------------------------------------------------------------------------------------|---------------------------|-----------------------| -| **Logging level** | Sets how verbose Logger should be (INFO, by default). Supported values are: `DEBUG`, `INFO`, `WARN`, `ERROR` | `LOG_LEVEL` | `logLevel` | -| **Service name** | Sets the name of service of which the Lambda function is part of, that will be present across all log statements | `POWERTOOLS_SERVICE_NAME` | `serviceName` | - -For a **complete list** of supported environment variables, refer to [this section](./../index.md#environment-variables). +| Setting | Description | Environment variable | Constructor parameter | +|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------|-----------------------| +| **Service name** | Sets the name of service of which the Lambda function is part of, that will be present across all log statements | `POWERTOOLS_SERVICE_NAME` | `serviceName` | +| **Logging level** | Sets how verbose Logger should be (INFO, by default). Supported values are: `DEBUG`, `INFO`, `WARN`, `ERROR` | `LOG_LEVEL` | `logLevel` | +| **Log incoming event** | Whether to log or not the incoming event when using the decorator or middleware. Supported values are: `true`, or `false`, disabled by default | `POWERTOOLS_LOGGER_LOG_EVENT` | `logEvent` | +| **Debug log sampling** | Probability that a Lambda invocation will print all the log items regardless of the log level setting. Supported values range from `0.0` to `1` | `POWERTOOLS_LOGGER_SAMPLE_RATE` | `sampleRateValue` | #### Example using AWS Serverless Application Model (SAM) diff --git a/docs/core/metrics.md b/docs/core/metrics.md index e2770de640..3b2d4baa3f 100644 --- a/docs/core/metrics.md +++ b/docs/core/metrics.md @@ -68,10 +68,8 @@ These settings will be used across all metrics emitted: | Setting | Description | Environment variable | Constructor parameter | |----------------------|---------------------------------------------------------------------------------|--------------------------------|-----------------------| -| **Metric namespace** | Logical container where all metrics will be placed e.g. `serverlessAirline` | `POWERTOOLS_METRICS_NAMESPACE` | `namespace` | | **Service** | Optionally, sets **service** metric dimension across all metrics e.g. `payment` | `POWERTOOLS_SERVICE_NAME` | `serviceName` | - -For a **complete list** of supported environment variables, refer to [this section](./../index.md#environment-variables). +| **Metric namespace** | Logical container where all metrics will be placed e.g. `serverlessAirline` | `POWERTOOLS_METRICS_NAMESPACE` | `namespace` | !!! tip Use your application name or main service as the metric namespace to easily group all metrics @@ -299,7 +297,7 @@ Using the Middy middleware or decorator will **automatically validate, serialize If you do not use the middleware or decorator, you have to flush your metrics manually. !!! warning "Metric validation" - If metrics are provided, and any of the following criteria are not met, a **`RangeError`** exception will be thrown: + If metrics are provided, and any of the following criteria are not met, a **`RangeError`** error will be thrown: * Maximum of 29 dimensions * Namespace is set only once (or none) diff --git a/docs/core/tracer.md b/docs/core/tracer.md index bba9442920..7712e8a65c 100644 --- a/docs/core/tracer.md +++ b/docs/core/tracer.md @@ -50,13 +50,13 @@ The `Tracer` utility must always be instantiated outside of the Lambda handler. The library has three optional settings. You can set them as environment variables, or pass them in the constructor: -Setting | Description | Environment variable | Constructor parameter -------------------------------------------------- |------------------------------------------------------------------------------------------------| ------------------------------------------------- | ------------------------------------------------- -**Tracing enabled** | Enables or disables tracing. By default tracing is enabled when running in AWS Lambda. | `POWERTOOLS_TRACE_ENABLED` | `enabled` -**Service name** | Sets an annotation with the **name of the service** across all traces e.g. `serverlessAirline` | `POWERTOOLS_SERVICE_NAME` | `serviceName` -**Capture HTTPs Requests** | Defines whether HTTPs requests will be traced or not, enabled by default when tracing is also enabled. | `POWERTOOLS_TRACER_CAPTURE_HTTPS_REQUESTS` | `captureHTTPsRequests` - -For a **complete list** of supported environment variables, refer to [this section](./../index.md#environment-variables). +| Setting | Description | Environment variable | Constructor parameter | +|----------------------------|-----------------------------------------------------------------------------------------------------------------| -------------------------------------------|------------------------| +| **Service name** | Sets an annotation with the **name of the service** across all traces e.g. `serverlessAirline` | `POWERTOOLS_SERVICE_NAME` | `serviceName` | +| **Tracing enabled** | Enables or disables tracing. By default tracing is enabled when running in AWS Lambda | `POWERTOOLS_TRACE_ENABLED` | `enabled` | +| **Capture HTTPs Requests** | Defines whether HTTPs requests will be traced or not, enabled by default when tracing is also enabled | `POWERTOOLS_TRACER_CAPTURE_HTTPS_REQUESTS` | `captureHTTPsRequests` | +| **Capture Response** | Defines whether functions responses are serialized as metadata, enabled by default when tracing is also enabled | `POWERTOOLS_TRACER_CAPTURE_RESPONSE` | `captureResult` | +| **Capture Errors** | Defines whether functions errors are serialized as metadata, enabled by default when tracing is also enabled | `POWERTOOLS_TRACER_CAPTURE_ERROR` | N/A | !!! note Before your use this utility, your AWS Lambda function must have [Active Tracing enabled](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html) as well as [have permissions](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html#services-xray-permissions) to send traces to AWS X-Ray @@ -476,13 +476,13 @@ Alternatively, use the `captureResponse: false` option in both `tracer.captureLa .use(captureLambdaHandler(tracer, { captureResponse: false })); ``` -### Disabling exception auto-capture +### Disabling errors auto-capture -Use **`POWERTOOLS_TRACER_CAPTURE_ERROR=false`** environment variable to instruct Tracer **not** to serialize exceptions as metadata. +Use **`POWERTOOLS_TRACER_CAPTURE_ERROR=false`** environment variable to instruct Tracer **not** to serialize errors as metadata. !!! info "Commonly useful in one scenario" - 1. You might **return sensitive** information from exceptions, stack traces you might not control + 1. You might **return sensitive** information from errors, stack traces you might not control ### Escape hatch mechanism diff --git a/docs/index.md b/docs/index.md index 1cdb6b49a8..25ac163ad2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,41 +3,31 @@ title: Homepage description: AWS Lambda Powertools for TypeScript --- -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. +A suite of utilities for AWS Lambda functions running on the Node.js runtime, to ease adopting best practices such as tracing, structured logging, custom metrics, [**and more**](#features). -You can use the library in both TypeScript and JavaScript code bases. +You can use Powertools 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. +???+ tip + Powertools is also available for [Python](https://awslabs.github.io/aws-lambda-powertools-python/){target="_blank"}, [Java](https://awslabs.github.io/aws-lambda-powertools-java/latest/){target="_blank"}, and [.NET](https://awslabs.github.io/aws-lambda-powertools-dotnet/){target="_blank"} -* **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. +??? hint "Support this project by becoming a reference customer, sharing your work, or using Layers :heart:" -## Features + You can choose to support us in three ways: -| Utility | Description -| ------------------------------------------------- | --------------------------------------------------------------------------------- -[Tracer](./core/tracer.md) | Trace Lambda function handlers, and both synchronous and asynchronous functions -[Logger](./core/logger.md) | Structured logging made easier, and a middleware to enrich log items with key details of the Lambda context -[Metrics](./core/metrics.md) | Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF) + 1) [**Become a reference customers**](https://github.com/awslabs/aws-lambda-powertools-typescript/issues/new?assignees=&labels=customer-reference&template=support_powertools.yml&title=%5BSupport+Lambda+Powertools%5D%3A+%3Cyour+organization+name%3E). This gives us permission to list your company in our documentation. -## Installation + 2) [**Share your work**](https://github.com/awslabs/aws-lambda-powertools-typescript/issues/new?assignees=&labels=community-content&template=share_your_work.yml&title=%5BI+Made+This%5D%3A+%3CTITLE%3E). Blog posts, video, sample projects you used Powertools! -You can use Powertools through [AWS Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-concepts.html#gettingstarted-concepts-layer) or install it as your dependency via NPM: + 3) Use [**Lambda Layers**](#lambda-layer), if possible. This helps us understand who uses Powertools in a non-intrusive way, and helps us gain future investments for other Lambda Powertools languages. -* **Lambda Layer**: [**arn:aws:lambda:{region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:3**](#){: .copyMe}:clipboard: -* **NPM**: **`npm install @aws-lambda-powertools/tracer @aws-lambda-powertools/metrics @aws-lambda-powertools/logger`** + When using Layers, you can add Lambda Powertools as a `devDependency` to not impact the development process. -???+ hint "Support this project by using Lambda Layers :heart:" - Lambda Layers allow us to understand who uses this library in a non-intrusive way. This helps us justify and gain future investments for other Lambda Powertools languages. +## Install - When using Layers, you can add Lambda Powertools as a dev dependency to not impact the development process. +Powertools is available in the following formats: +* **Lambda Layer**: [**arn:aws:lambda:{region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:3**](#){: .copyMe}:clipboard: +* **npm**: **`npm install @aws-lambda-powertools/tracer @aws-lambda-powertools/metrics @aws-lambda-powertools/logger`** ### Lambda Layer @@ -45,7 +35,7 @@ You can use Powertools through [AWS Lambda Layer](https://docs.aws.amazon.com/la You can include Lambda Powertools Lambda Layer using [AWS Lambda Console](https://docs.aws.amazon.com/lambda/latest/dg/invocation-layers.html#invocation-layers-using){target="_blank"}, or your preferred deployment framework. -??? note "Note: Expand to copy any regional Lambda Layer ARN" +??? note "Note: Click to expand and copy any regional Lambda Layer ARN" | Region | Layer ARN |--------------------------- | --------------------------- @@ -67,206 +57,171 @@ You can include Lambda Powertools Lambda Layer using [AWS Lambda Console](https: | `ca-central-1` | [arn:aws:lambda:ca-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScript:3](#){: .copyMe}:clipboard: | `sa-east-1` | [arn:aws:lambda:sa-east-1:094274105915:layer:AWSLambdaPowertoolsTypeScript:3](#){: .copyMe}:clipboard: -??? question "Can't find our Lambda Layer for your preferred AWS region?" - You can use our [CDK Layer Construct](https://github.com/aws-samples/cdk-lambda-powertools-python-layer){target="_blank"}, or NPM like you normally would for any other library. +??? note "Note: Click to expand and copy code snippets for popular frameworks" + + === "SAM" + + ```yaml hl_lines="5" + MyLambdaFunction: + Type: AWS::Serverless::Function + Properties: + Layers: + - !Sub arn:aws:lambda:${AWS::Region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:3 + ``` + + If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools` from being bundled since the packages will be already present the Layer: + + ```yaml hl_lines="5" + MyLambdaFunction: + Type: AWS::Serverless::Function + Properties: + ... + Metadata: + # Manage esbuild properties + BuildMethod: esbuild + BuildProperties: + Minify: true + External: + - '@aws-lambda-powertools/commons' + - '@aws-lambda-powertools/logger' + - '@aws-lambda-powertools/metrics' + - '@aws-lambda-powertools/tracer' + ``` + + Check the [documentation](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-using-build-typescript.html) for more details. + + === "Serverless framework" + + ```yaml hl_lines="5" + functions: + hello: + handler: lambda_function.lambda_handler + layers: + - arn:aws:lambda:${aws::region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:3 + ``` + + If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools` from being bundled since the packages will be already present the Layer: + + ```yaml + custom: + esbuild: + external: + - '@aws-lambda-powertools/commons' + - '@aws-lambda-powertools/logger' + - '@aws-lambda-powertools/metrics' + - '@aws-lambda-powertools/tracer' + ``` + + Check the [documentation](https://floydspace.github.io/serverless-esbuild/) for more details. + + === "CDK" + + ```typescript hl_lines="13 19" + import * as cdk from 'aws-cdk-lib'; + import { Construct } from 'constructs'; + import * as lambda from 'aws-cdk-lib/aws-lambda'; + + export class SampleFunctionWithLayer extends Construct { + constructor(scope: Construct, id: string) { + super(scope, id); + + // Create a Layer with AWS Lambda Powertools for TypeScript + const powertoolsLayer = lambda.LayerVersion.fromLayerVersionArn( + this, + 'PowertoolsLayer', + `arn:aws:lambda:${cdk.Stack.of(this).region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:3` + ); + + new lambda.Function(this, 'Function', { + runtime: lambda.Runtime.NODEJS_16_X, + // Add the Layer to a Lambda function + layers: [powertoolsLayer], + code: lambda.Code.fromInline(`...`), + handler: 'index.handler', + }); + } + } + ``` + + If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools` from being bundled since the packages will be already present the Layer: + + ```typescript + new awsLambdaNodejs.NodejsFunction(this, 'Function', { + ... + bundling: { + externalModules: [ + '@aws-lambda-powertools/commons', + '@aws-lambda-powertools/logger', + '@aws-lambda-powertools/metrics', + '@aws-lambda-powertools/tracer', + ], + } + }); + ``` - Please do file a feature request with the region you'd want us to prioritize making our Lambda Layer available. + Check the [documentation](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs.BundlingOptions.html#externalmodules) for more details. -=== "SAM" + === "Terraform" - ```yaml hl_lines="5" - MyLambdaFunction: - Type: AWS::Serverless::Function - Properties: - Layers: - - !Sub arn:aws:lambda:${AWS::Region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:3 - ``` + ```terraform hl_lines="9 36" + terraform { + required_version = "~> 1.0.5" + required_providers { + aws = "~> 3.50.0" + } + } -=== "Serverless framework" + provider "aws" { + region = "{aws::region}" + } - ```yaml hl_lines="5" - functions: - hello: - handler: lambda_function.lambda_handler - layers: - - arn:aws:lambda:${aws::region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:3 - ``` + resource "aws_lambda_function" "test_lambda" { + filename = "lambda_function_payload.zip" + function_name = "lambda_function_name" + role = ... + handler = "index.handler" + runtime = "nodejs16.x" + layers = ["arn:aws:lambda:{aws::region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:3"] + source_code_hash = filebase64sha256("lambda_function_payload.zip") + } + ``` -=== "CDK" + === "Amplify" - ```typescript hl_lines="13 19" - import * as cdk from 'aws-cdk-lib'; - import { Construct } from 'constructs'; - import * as lambda from 'aws-cdk-lib/aws-lambda'; - - export class SampleFunctionWithLayer extends Construct { - constructor(scope: Construct, id: string) { - super(scope, id); - - // Create a Layer with AWS Lambda Powertools for TypeScript - const powertoolsLayer = lambda.LayerVersion.fromLayerVersionArn( - this, - 'PowertoolsLayer', - `arn:aws:lambda:${cdk.Stack.of(this).region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:3` - ); + ```zsh + # Create a new one with the layer + ❯ amplify add function + ? Select which capability you want to add: Lambda function (serverless function) + ? Provide an AWS Lambda function name: + ? Choose the runtime that you want to use: NodeJS + ? Do you want to configure advanced settings? Yes + ... + ? Do you want to enable Lambda layers for this function? Yes + ? Enter up to 5 existing Lambda layer ARNs (comma-separated): arn:aws:lambda:{aws::region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:3 + ❯ amplify push -y - new lambda.Function(this, 'Function', { - runtime: lambda.Runtime.NODEJS_16_X, - // Add the Layer to a Lambda function - layers: [powertoolsLayer], - code: lambda.Code.fromInline(`...`), - handler: 'index.handler', - }); - } - } - ``` - -=== "Terraform" - - ```terraform hl_lines="9 36" - terraform { - required_version = "~> 1.0.5" - required_providers { - aws = "~> 3.50.0" - } - } - - provider "aws" { - region = "{aws::region}" - } - - resource "aws_iam_role" "iam_for_lambda" { - name = "iam_for_lambda" - assume_role_policy = < - ? Choose the runtime that you want to use: NodeJS - ? Do you want to configure advanced settings? Yes - ... - ? Do you want to enable Lambda layers for this function? Yes - ? Enter up to 5 existing Lambda layer ARNs (comma-separated): arn:aws:lambda:{aws::region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:3 - ❯ amplify push -y - # Updating an existing function and add the layer - ❯ amplify update function - ? Select the Lambda function you want to update test2 - General information - - Name: - ? Which setting do you want to update? Lambda layers configuration - ? Do you want to enable Lambda layers for this function? Yes - ? Enter up to 5 existing Lambda layer ARNs (comma-separated): arn:aws:lambda:{aws::region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:3 - ? Do you want to edit the local lambda function now? No - ``` - -=== "Get the Layer .zip contents" - ```bash title="AWS CLI" - aws lambda get-layer-version-by-arn --arn arn:aws:lambda:{aws::region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:3 --region {region} - ``` - - The pre-signed URL to download this Lambda Layer will be within `Location` key. + # Updating an existing function and add the layer + ❯ amplify update function + ? Select the Lambda function you want to update test2 + General information + - Name: + ? Which setting do you want to update? Lambda layers configuration + ? Do you want to enable Lambda layers for this function? Yes + ? Enter up to 5 existing Lambda layer ARNs (comma-separated): arn:aws:lambda:{aws::region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:3 + ? Do you want to edit the local lambda function now? No + ``` + + === "Get the Layer .zip contents" + ```bash title="AWS CLI" + aws lambda get-layer-version-by-arn --arn arn:aws:lambda:{aws::region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:3 --region {region} + ``` + + The pre-signed URL to download this Lambda Layer will be within `Location` key. ???+ warning "Warning: Limitations" Container Image deployment (OCI) or inline Lambda functions do not support Lambda Layers. -If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools` from being bundled since the packages will be brought by the Layer: - -=== "SAM (check the [doc](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-using-build-typescript.html) for more details)" - - ```yaml hl_lines="5" - MyLambdaFunction: - Type: AWS::Serverless::Function - Properties: - ... - Metadata: - # Manage esbuild properties - BuildMethod: esbuild - BuildProperties: - Minify: true - External: - - '@aws-lambda-powertools/commons' - - '@aws-lambda-powertools/logger' - - '@aws-lambda-powertools/metrics' - - '@aws-lambda-powertools/tracer' - ``` - -=== "Serverless framework (check the [doc](https://floydspace.github.io/serverless-esbuild/) for more details)" - - ```yaml hl_lines="5" - custom: - esbuild: - external: - - '@aws-lambda-powertools/commons' - - '@aws-lambda-powertools/logger' - - '@aws-lambda-powertools/metrics' - - '@aws-lambda-powertools/tracer' - ``` - -=== "CDK (check the [doc](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs.BundlingOptions.html#externalmodules) for more details)" - - ```typescript hl_lines="11 16" - new awsLambdaNodejs.NodejsFunction(this, 'Function', { - ... - bundling: { - externalModules: [ - '@aws-lambda-powertools/commons', - '@aws-lambda-powertools/logger', - '@aws-lambda-powertools/metrics', - '@aws-lambda-powertools/tracer', - ], - } - }); - ``` - -### NPM Modules - -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](https://github.com/aws/aws-sdk-js-v3). -Each TypeScript utility is installed as standalone NPM package. - -Install all three core utilities at once with this single command: - -```shell -npm install @aws-lambda-powertools/logger @aws-lambda-powertools/tracer @aws-lambda-powertools/metrics -``` - - -Or refer to the installation guide of each utility: - -[Installation guide for the **Tracer** utility](./core/tracer.md#getting-started) - -[Installation guide for the **Logger** utility](./core/logger.md#getting-started) - -[Installation guide for the **Metrics** utility](./core/metrics.md#getting-started) ## Instrumentation @@ -278,10 +233,29 @@ You can instrument your code with Powertools in three different ways: The examples in this documentation will feature all the approaches described above, when applicable. +## Examples + +The project's repository includes examples of how to instrument your functions both in AWS CDK and AWS SAM: + +* [AWS CDK](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk){target="_blank"} +* [AWS SAM](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/sam){target="_blank"} + +If instead you want to see Powertools for TypeScript in a slightly more complex use case, check the [Serverless TypeScript Demo](https://github.com/aws-samples/serverless-typescript-demo). You can find instructions on how to deploy and load test this application in the [repository](https://github.com/aws-samples/serverless-typescript-demo). + +## Features + +Core utilities such as Tracing, Logging, and Metrics will be available across all Lambda Powertools languages. Additional utilities are subjective to each language ecosystem and customer demand. + +| Utility | Description | +| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| [Tracer](./core/tracer.md) | Decorators and utilities to trace Lambda function handlers, and both synchronous and asynchronous functions | +| [Logger](./core/logger.md) | Structured logging made easier, and a middleware to enrich structured logging with key Lambda context details | +| [Metrics](./core/metrics.md) | Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF) | + ## Environment variables -!!! info - **Explicit parameters passed in constructors or in middleware/decorators take precedence over environment variables.** +???+ info + Explicit parameters take precedence over environment variables | Environment variable | Description | Utility | Default | |----------------------------------------------|----------------------------------------------------------------------------------------|---------------------------|-----------------------| @@ -295,35 +269,14 @@ The examples in this documentation will feature all the approaches described abo | **POWERTOOLS_LOGGER_SAMPLE_RATE** | Debug log sampling | [Logger](./core/logger) | `0` | | **LOG_LEVEL** | Sets logging level | [Logger](./core/logger) | `INFO` | -## Examples - -* [CDK](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk){target="_blank"} -* [SAM](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/sam){target="_blank"} - -## Serverless TypeScript demo application - -The [Serverless TypeScript Demo](https://github.com/aws-samples/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](https://github.com/aws-samples/serverless-typescript-demo). - -## Contribute - -If you are interested in contributing to this project, please refer to our [Contributing Guidelines](https://github.com/awslabs/aws-lambda-powertools-typescript/blob/main/CONTRIBUTING.md). - -## Roadmap - -The roadmap of Powertools is driven by customers’ demand. -Help us prioritize upcoming functionalities or utilities by [upvoting existing RFCs and feature requests](https://github.com/awslabs/aws-lambda-powertools-typescript/issues), or [creating new ones](https://github.com/awslabs/aws-lambda-powertools-typescript/issues/new/choose), in this GitHub repository. - -## Connect - -* **AWS Lambda Powertools on Discord**: `#typescript` - **[Invite link](https://discord.gg/B8zZKbbyET){target="_blank"}** -* **Email**: aws-lambda-powertools-feedback@amazon.com - -## Credits - -Credits for the Lambda Powertools idea go to [DAZN](https://github.com/getndazn){target="_blank"} and their [DAZN Lambda Powertools](https://github.com/getndazn/dazn-lambda-powertools/){target="_blank"}. - -## License +## Tenets -This library is licensed under the MIT-0 License. See the [LICENSE](https://github.com/awslabs/aws-lambda-powertools-typescript/blob/main/LICENSE) file. +These are our core principles to guide our decision making. +* **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. + \ No newline at end of file