Skip to content

docs(all): getting started section, beta release warning #351

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Dec 28, 2021
Merged

docs(all): getting started section, beta release warning #351

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0974dc8
docs(all): getting started section, beta release warning
saragerion Dec 27, 2021
ba37617
docs(all): readme files, docs getting started guide, third party lice…
saragerion Dec 27, 2021
54aa785
chore(all): merge
saragerion Dec 28, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions LICENSE-THIRD-PARTY
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
59 changes: 40 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I removed this one because I realized it was a python library

* 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.
83 changes: 54 additions & 29 deletions docs/core/logger.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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"

Expand All @@ -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"
// });
```
Expand All @@ -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
```

Expand All @@ -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';

Expand All @@ -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"

Expand All @@ -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);

Expand All @@ -106,7 +141,7 @@ Method 2, calling the `addContext` method:
};
```

Method 3, using a class decorator:
#### Method 3, using a class decorator:

=== "handler.ts"

Expand All @@ -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"

Expand All @@ -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:
Expand Down Expand Up @@ -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"

Expand Down
25 changes: 24 additions & 1 deletion docs/core/metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,13 @@ title: Metrics
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.**

Metrics creates custom metrics asynchronously by logging metrics to standard output following [Amazon CloudWatch Embedded Metric Format (EMF)](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format.html).

These metrics can be visualized through [Amazon CloudWatch Console](https://console.aws.amazon.com/cloudwatch/).
Expand All @@ -28,13 +35,29 @@ If you're new to Amazon CloudWatch, there are two terminologies you must be awar

## Getting started

Metric has two global settings that will be used across all metrics emitted:
### Installation

Install the library in your project:

```shell

npm install @aws-lambda-powertools/metrics

```

### Utility settings

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 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` | `service`

For a **complete list** of supported environment variables, refer to [this section](./../index.md#environment-variables).

!!! tip "Use your application or main service as the metric namespace to easily group all metrics"

> Example using AWS Serverless Application Model (SAM)
Expand Down
Loading