Resolving merge conflicts

Author: dreamorosi

CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.2.0-beta.8](https://github.com/awslabs/aws-lambda-powertools-typescript/compare/v0.2.0-beta.7...v0.2.0-beta.8) (2021-12-28)
+
+**Note:** Version bump only for package aws-lambda-powertools-typescript
+
+
+
+
+
+# [0.2.0-beta.7](https://github.com/awslabs/aws-lambda-powertools-typescript/compare/v0.2.0-beta.6...v0.2.0-beta.7) (2021-12-27)
+
+
+### Features
+
+* **metrics:** logMetrics middleware ([#338](https://github.com/awslabs/aws-lambda-powertools-typescript/issues/338)) ([f8cf705](https://github.com/awslabs/aws-lambda-powertools-typescript/commit/f8cf7055de78e4515ffbae5de5867649a38dc17d))
+
+
+
+
+
 # [0.2.0-beta.6](https://github.com/awslabs/aws-lambda-powertools-typescript/compare/v0.2.0-beta.5...v0.2.0-beta.6) (2021-12-23)
 
 **Note:** Version bump only for package aws-lambda-powertools-typescript

LICENSE-THIRD-PARTY

@@ -0,0 +1,57 @@
+hosted-git-info
+4.0.2 <https://github.com/npm/hosted-git-info>
+Copyright (c) 2015, Rebecca Turner
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+
+
+******************************
+
+lru-cache
+6.0.0 <https://github.com/isaacs/node-lru-cache>
+The ISC License
+
+Copyright (c) Isaac Z. Schlueter and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+
+******************************
+
+yallist
+4.0.0 <https://github.com/isaacs/yallist>
+The ISC License
+
+Copyright (c) Isaac Z. Schlueter and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

README.md

@@ -1,34 +1,55 @@
-# AWS Lambda Powertools (TypeScript)
-![Tests](https://github.com/awslabs/aws-lambda-powertools-typescript/workflows/Test/badge.svg?branch=main)
-## Testing
-The repo uses JEST tests, these can be run using
+# AWS Lambda Powertools TypeScript
 
-`npm run lerna-test`
+| ⚠️ **WARNING: 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.  <br/>This version is not stable, and significant breaking changes might incur as part of the upcoming [production-ready release](https://github.com/awslabs/aws-lambda-powertools-typescript/milestone/2).                                              |_
 
-Which will also generate coverage reports, and fail if the coverage is below the threshold.
 
-## Code Styling and Linting
-### Linting
-Linting standards adhear to [tslint:recommended](https://github.com/palantir/tslint/blob/master/src/configs/recommended.ts).
+A suite of TypeScript utilities for AWS Lambda functions to ease adopting best practices such as tracing, structured logging, custom metrics, and more. (AWS Lambda Powertools [Python](https://github.com/awslabs/aws-lambda-powertools-python) and [Java](https://github.com/awslabs/aws-lambda-powertools-java) are also available).
 
-Please ensure you run `npm run lerna-lint` before comiting to check for styling errors
+**[📜 Documentation](https://awslabs.github.io/aws-lambda-powertools-typescript/)** | **[NPM](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Roadmap](https://github.com/awslabs/aws-lambda-powertools-roadmap/projects/1)** | **[Examples](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk)**
 
-### Formating
+> **An AWS Developer Acceleration (DevAx) initiative by Specialist Solution Architects | [email protected]**
 
-The repo is setup using  [Prettier](https://prettier.io/). This will automatically make syntactic changes to files to
-align them with the style guides. Please run this before creating a PR, and commit the changes.
+### Features
 
-`npm run lerna-format`
+* **[Tracer](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/tracer/)** - Utilities to trace Lambda function handlers, and both synchronous and asynchronous functions
+* **[Logger](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/logger/)** - Structured logging made easier, and a middleware to enrich log items with key details of the Lambda context
+* **[Metrics](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/metrics/)** - Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF)
+
+
+## Getting started
+
+Find the complete project's [documentation here](https://awslabs.github.io/aws-lambda-powertools-typescript).
+
+### Installation
+
+The AWS Lambda Powertools TypeScript utilities 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.
+
+👉 [Installation guide for the **Tracer** utility](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/tracer#getting-started)
+
+👉 [Installation guide for the **Logger** utility](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/logger#getting-started)
+
+👉 [Installation guide for the **Metrics** utility](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/metrics#getting-started)
+
+### Examples
+
+* [CDK](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk)
+* [Tracer](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/packages/tracing/examples)
+* [Logger](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/packages/logger/examples)
+* [Metrics](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/packages/metrics/examples)
 
 ## Credits
 
-* Structured logging initial implementation from [aws-lambda-logging](https://gitlab.com/hadrien/aws_lambda_logging)
-* Powertools idea [DAZN Powertools](https://github.com/getndazn/dazn-lambda-powertools/)
+* Credits for the Lambda Powertools idea go to [DAZN](https://github.com/getndazn) and their [DAZN Lambda Powertools](https://github.com/getndazn/dazn-lambda-powertools/).
+
 
-## Security
+## Connect
 
-See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
+* **AWS Developers Slack**: `#lambda-powertools`** - **[Invite, if you don't have an account](https://join.slack.com/t/awsdevelopers/shared_invite/zt-yryddays-C9fkWrmguDv0h2EEDzCqvw)**
+* **Email**: [email protected]
 
 ## License
 
-This library is licensed under the MIT-0 License. See the [LICENSE](LICENSE) file.
+This library is licensed under the MIT-0 License. See the LICENSE file.

docs/core/logger.md

@@ -3,6 +3,14 @@ title: Logger
 description: Core utility
 ---
 
+!!! warning  "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](https://github.com/awslabs/aws-lambda-powertools-typescript/milestone/2){target="_blank"}.
+
+    **Do not use this library for production workloads.**
+
+
 Logger provides an opinionated logger with output structured as JSON.
 
 ## Key features
@@ -14,14 +22,31 @@ Logger provides an opinionated logger with output structured as JSON.
 
 ## Getting started
 
-Logger requires two settings:
+### Installation
+
+Install the library in your project:
+
+```shell
+
+npm install @aws-lambda-powertools/logger
+
+```
+
+### Utility settings
 
-Setting | Description | Environment variable | Constructor parameter
-------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------
-**Logging level** | Sets how verbose Logger should be (INFO, by default) |  `LOG_LEVEL` | `logLevel`
+The library requires two settings. You can set them as environment variables, or pass them in the constructor.
+
+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`
 
-> Example using AWS Serverless Application Model (SAM)
+
+For a **complete list** of supported environment variables, refer to [this section](./../index.md#environment-variables).
+
+#### Example using AWS Serverless Application Model (SAM)
 
 === "handler.ts"
 
@@ -33,7 +58,7 @@ Setting | Description | Environment variable | Constructor parameter
 
     // You can also pass the parameters in the constructor
     // const logger = new Logger({
-    //     logLevel: "INFO",
+    //     logLevel: "WARN",
     //     serviceName: "shopping-cart-api"
     // });
     ```
@@ -48,7 +73,7 @@ Setting | Description | Environment variable | Constructor parameter
           Runtime: nodejs14.x
           Environment:
             Variables:
-              LOG_LEVEL: INFO
+              LOG_LEVEL: WARN
               POWERTOOLS_SERVICE_NAME: shopping-cart-api
     ```
 
@@ -70,11 +95,21 @@ Key | Example | Note
 
 You can enrich your structured logs with key Lambda context information in multiple ways.
 
-Method 1, using a [Middy](https://github.com/middyjs/middy) middleware:
+This functionality will include the following keys in your structured logs:
+
+Key | Example
+------------------------------------------------- | ---------------------------------------------------------------------------------
+**cold_start**: `bool` | `false`
+**function_name** `string` | `shopping-cart-api-lambda-prod-eu-central-1`
+**function_memory_size**: `number` | `128`
+**function_arn**: `string` | `arn:aws:lambda:eu-central-1:123456789012:function:shopping-cart-api-lambda-prod-eu-central-1`
+**function_request_id**: `string` | `c6af9ac6-7b61-11e6-9a41-93e812345678`
+
+#### Method 1, using a [Middy](https://github.com/middyjs/middy) middleware:
 
 === "handler.ts"
 
-    ```typescript hl_lines="1 9-10"
+    ```typescript hl_lines="1 9-11"
     import { Logger, injectLambdaContext } from "@aws-lambda-powertools/logger";
     import middy from '@middy/core';
 
@@ -88,7 +123,7 @@ Method 1, using a [Middy](https://github.com/middyjs/middy) middleware:
         .use(injectLambdaContext(logger));
     ```
 
-Method 2, calling the `addContext` method:
+#### Method 2, calling the `addContext` method:
 
 === "handler.ts"
 
@@ -97,7 +132,7 @@ Method 2, calling the `addContext` method:
 
     const logger = new Logger();
 
-    const lambdaHandler = async () => {
+    const lambdaHandler = async (_event, context) => {
 
         logger.addContext(context);
         
@@ -106,7 +141,7 @@ Method 2, calling the `addContext` method:
     };
     ```
 
-Method 3, using a class decorator:
+#### Method 3, using a class decorator:
 
 === "handler.ts"
 
@@ -125,7 +160,7 @@ Method 3, using a class decorator:
     }
     ```
 
-In both case, the printed log will look like this:
+In each case, the printed log will look like this:
 
 === "Example CloudWatch Logs excerpt"
 
@@ -144,16 +179,6 @@ In both case, the printed log will look like this:
     }
     ```
 
-When used, this will include the following keys:
-
-Key | Example
-------------------------------------------------- | ---------------------------------------------------------------------------------
-**cold_start**: `bool` | `false`
-**function_name** `string` | `shopping-cart-api-lambda-prod-eu-central-1`
-**function_memory_size**: `int` | `128`
-**function_arn**: `string` | `arn:aws:lambda:eu-central-1:123456789012:function:shopping-cart-api-lambda-prod-eu-central-1`
-**function_request_id**: `string` | `c6af9ac6-7b61-11e6-9a41-93e812345678`
-
 ### Appending persistent additional log keys and values
 
 You can append additional persistent keys and values in the logs generated during a Lambda invocation using either mechanism:
@@ -422,12 +447,12 @@ This number represents the probability that a Lambda invocation will print all t
 For example, by setting the "sample rate" to `0.5`, roughly 50% of your lambda invocations will print all the log items, including the `debug` ones.
 
 !!! tip "When is this useful?"
-In production, to avoid log data pollution and reduce CloudWatch costs, developers are encouraged to use the logger with `logLevel` equal to `ERROR` or `WARN`.
-This means that only errors or warnings will be printed. 
-
-However, it might still be useful to print all the logs (including debug ones) of a very small percentage of invocations to have a better understanding of the behaviour of your code in production even when there are no errors.
-
-Sampling decision happens at the Logger initialization. This means sampling may happen significantly more or less than depending on your traffic patterns, for example a steady low number of invocations and thus few cold starts.
+    In production, to avoid log data pollution and reduce CloudWatch costs, developers are encouraged to use the logger with `logLevel` equal to `ERROR` or `WARN`.
+    This means that only errors or warnings will be printed. 
+    
+    However, it might still be useful to print all the logs (including debug ones) of a very small percentage of invocations to have a better understanding of the behaviour of your code in production even when there are no errors.
+    
+    Sampling decision happens at the Logger initialization. This means sampling may happen significantly more or less than depending on your traffic patterns, for example a steady low number of invocations and thus few cold starts.
 
 === "handler.ts"