From 970ddcffe4bd5e577c46f75db3905846eb8eeaa7 Mon Sep 17 00:00:00 2001 From: Sara Gerion Date: Mon, 18 Jul 2022 15:46:09 +0200 Subject: [PATCH 1/2] docs: consistency with blog post messaging, added one-line installation command, reduce font size --- README.md | 30 ++++++++++++++++++++++---- docs/core/logger.md | 9 ++++---- docs/core/metrics.md | 8 +++---- docs/core/tracer.md | 10 ++++----- docs/index.md | 24 ++++++++++++++++++++- docs/stylesheets/extra.css | 12 ++++------- mkdocs.yml | 2 ++ packages/logger/README.md | 43 ++++++++++++++++++++++++++++++++------ packages/metrics/README.md | 40 +++++++++++++++++++++++++++++++---- packages/tracer/README.md | 38 ++++++++++++++++++++++++++++++--- 10 files changed, 177 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index ec91a2511c..e802a7a8d7 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # AWS Lambda Powertools for TypeScript -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 for [Python](https://github.com/awslabs/aws-lambda-powertools-python) and AWS Lambda Powertools for [Java](https://github.com/awslabs/aws-lambda-powertools-java) are also available). +A suite of utilities for AWS Lambda functions 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. +AWS Lambda Powertools for [Python](https://github.com/awslabs/aws-lambda-powertools-python) and AWS Lambda Powertools for [Java](https://github.com/awslabs/aws-lambda-powertools-java) are also available). -**[📜 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)** - -> **An AWS Developer Acceleration (DevAx) initiative by Specialist Solution Architects | aws-devax-open-source@amazon.com** +**[📜 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)** | **[Serverless TypeScript Demo](https://github.com/aws-samples/serverless-typescript-demo)** ## Table of contents @@ -31,6 +31,14 @@ Find the complete project's [documentation here](https://awslabs.github.io/aws-l The AWS Lambda Powertools for 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. +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](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) @@ -42,10 +50,24 @@ Each TypeScript utility is installed as standalone NPM package. * [CDK](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk) * [SAM](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/sam) +## 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). + ## Credits * 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/). +## Contribute + +If you want to contribute 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 Developers Slack**: `#lambda-powertools` - **[Invite, if you don't have an account](https://join.slack.com/t/awsdevelopers/shared_invite/zt-yryddays-C9fkWrmguDv0h2EEDzCqvw)** diff --git a/docs/core/logger.md b/docs/core/logger.md index 0c01dd6878..520773dcc8 100644 --- a/docs/core/logger.md +++ b/docs/core/logger.md @@ -7,10 +7,11 @@ Logger provides an opinionated logger with output structured as JSON. ## Key features -* Capture key fields from Lambda context, cold start and structure logging output as JSON -* Log Lambda event when instructed (disabled by default) -* Log sampling prints all the logs for a percentage of invocations (disabled by default) -* Append additional keys to structured log at any point in time +* Capturing key fields from the Lambda context, cold starts, and structure logging output as JSON. +* Logging Lambda invocation events when instructed (disabled by default). +* Printing all the logs only for a percentage of invocations via log sampling (disabled by default). +* Appending additional keys to structured logs at any point in time. +* Providing a custom log formatter (Bring Your Own Formatter) to output logs in a structure compatible with your organization’s Logging RFC. ## Getting started diff --git a/docs/core/metrics.md b/docs/core/metrics.md index c5e338931d..0cc7b04d1b 100644 --- a/docs/core/metrics.md +++ b/docs/core/metrics.md @@ -9,10 +9,10 @@ These metrics can be visualized through [Amazon CloudWatch Console](https://cons ## Key features -* Aggregate up to 100 metrics using a single CloudWatch EMF object (large JSON blob) -* Validate against common metric definitions mistakes (metric unit, values, max dimensions, max metrics, etc) -* Metrics are created asynchronously by CloudWatch service, no custom stacks needed -* Context manager to create a one off metric with a different dimension +* Aggregating up to 100 metrics using a single CloudWatch EMF object (large JSON blob). +* Validating your metrics against common metric definitions mistakes (for example, metric unit, values, max dimensions, max metrics). +* Metrics are created asynchronously by the CloudWatch service. You do not need any custom stacks, and there is no impact to Lambda function latency. +* Creating a one-off metric with different dimensions. ## Terminologies diff --git a/docs/core/tracer.md b/docs/core/tracer.md index 3a8aba1950..f613e9731e 100644 --- a/docs/core/tracer.md +++ b/docs/core/tracer.md @@ -7,11 +7,11 @@ Tracer is an opinionated thin wrapper for [AWS X-Ray SDK for Node.js](https://gi ## Key features -* 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 -* Automatically trace HTTP(s) clients and generate segments for each request -* Support tracing functions via decorators, middleware, and manual instrumentation -* Support tracing AWS SDK v2 and v3 via AWS X-Ray SDK for Node.js +* Auto-capturing cold start and service name as annotations, and responses or full exceptions as metadata. +* Automatically tracing HTTP(S) clients and generating segments for each request. +* Supporting tracing functions via decorators, middleware, and manual instrumentation. +* Supporting tracing AWS SDK v2 and v3 via AWS X-Ray SDK for Node.js. +* Auto-disable tracing when not running in the Lambda environment. ![Tracer showcase](../media/tracer_utility_showcase.png) diff --git a/docs/index.md b/docs/index.md index 8e9b0016bd..af17725c4e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,7 +3,8 @@ 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. +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 @@ -29,12 +30,28 @@ Core utilities such as Tracer, Logger, Metrics, and Event Handler will be availa 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 + +You can instrument your code with Powertools in three different ways: + +* **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](https://www.typescriptlang.org/docs/handbook/classes.html). +* **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](https://www.typescriptlang.org/docs/handbook/decorators.html#method-decorators) if you prefer writing your business logic using TypeScript Classes. If you aren’t using Classes, this requires the most significant refactoring. + ## Environment variables !!! info @@ -58,6 +75,11 @@ Each TypeScript utility is installed as standalone NPM package. * [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). + ## 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"}. diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 429ee3416c..1e7d781b9b 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -1,19 +1,15 @@ -.md-grid { - max-width: 81vw; +@font-face { + font-size: 0.65rem; } -.md-typeset table:not([class]) { - font-size: 0.75rem; +.md-grid { + max-width: 81vw; } .md-typeset a { border-bottom: 0.1px dashed black; } -.md-typeset table:not([class]) { - font-size: 0.75rem; -} - .md-nav__link--active { font-weight: bold; } diff --git a/mkdocs.yml b/mkdocs.yml index 315d7335a5..def0989f10 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -34,10 +34,12 @@ theme: - navigation.sections - navigation.expand - navigation.top + - toc.follow - navigation.instant - navigation.indexes - navigation.tracking - content.code.annotate + - toc.integrate icon: repo: fontawesome/brands/github logo: media/aws-logo-light.svg diff --git a/packages/logger/README.md b/packages/logger/README.md index c80504a494..6ad974300d 100644 --- a/packages/logger/README.md +++ b/packages/logger/README.md @@ -1,10 +1,20 @@ # AWS Lambda Powertools for TypeScript -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 for [Python](https://github.com/awslabs/aws-lambda-powertools-python) and AWS Lambda Powertools for [Java](https://github.com/awslabs/aws-lambda-powertools-java) are also available). +A suite of utilities for AWS Lambda functions 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. +AWS Lambda Powertools for [Python](https://github.com/awslabs/aws-lambda-powertools-python) and AWS Lambda Powertools for [Java](https://github.com/awslabs/aws-lambda-powertools-java) are also available). -**[📜 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)** +**[📜 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)** | **[Serverless TypeScript Demo](https://github.com/aws-samples/serverless-typescript-demo)** -> **An AWS Developer Acceleration (DevAx) initiative by Specialist Solution Architects | aws-devax-open-source@amazon.com** +## Table of contents + +- [Features](#features) +- [Getting started](#getting-started) + - [Installation](#installation) + - [Examples](#examples) +- [Credits](#credits) +- [Connect](#connect) +- [License](#license) ## Features @@ -12,7 +22,6 @@ A suite of TypeScript utilities for AWS Lambda functions to ease adopting best p * **[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). @@ -22,6 +31,14 @@ Find the complete project's [documentation here](https://awslabs.github.io/aws-l The AWS Lambda Powertools for 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. +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](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) @@ -33,15 +50,29 @@ Each TypeScript utility is installed as standalone NPM package. * [CDK](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk) * [SAM](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/sam) +## 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). + ## Credits * 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/). +## Contribute + +If you want to contribute 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 Developers Slack**: `#lambda-powertools`- **[Invite, if you don't have an account](https://join.slack.com/t/awsdevelopers/shared_invite/zt-yryddays-C9fkWrmguDv0h2EEDzCqvw)** +* **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**: aws-lambda-powertools-feedback@amazon.com ## License -This library is licensed under the MIT-0 License. See the LICENSE file. \ No newline at end of file +This library is licensed under the MIT-0 License. See the LICENSE file. diff --git a/packages/metrics/README.md b/packages/metrics/README.md index ca8913b7be..6ad974300d 100644 --- a/packages/metrics/README.md +++ b/packages/metrics/README.md @@ -1,10 +1,20 @@ # AWS Lambda Powertools for TypeScript -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 for [Python](https://github.com/awslabs/aws-lambda-powertools-python) and AWS Lambda Powertools for [Java](https://github.com/awslabs/aws-lambda-powertools-java) are also available). +A suite of utilities for AWS Lambda functions 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. +AWS Lambda Powertools for [Python](https://github.com/awslabs/aws-lambda-powertools-python) and AWS Lambda Powertools for [Java](https://github.com/awslabs/aws-lambda-powertools-java) are also available). -**[📜 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)** +**[📜 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)** | **[Serverless TypeScript Demo](https://github.com/aws-samples/serverless-typescript-demo)** -> **An AWS Developer Acceleration (DevAx) initiative by Specialist Solution Architects | aws-devax-open-source@amazon.com** +## Table of contents + +- [Features](#features) +- [Getting started](#getting-started) + - [Installation](#installation) + - [Examples](#examples) +- [Credits](#credits) +- [Connect](#connect) +- [License](#license) ## Features @@ -21,6 +31,14 @@ Find the complete project's [documentation here](https://awslabs.github.io/aws-l The AWS Lambda Powertools for 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. +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](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) @@ -32,10 +50,24 @@ Each TypeScript utility is installed as standalone NPM package. * [CDK](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk) * [SAM](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/sam) +## 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). + ## Credits * 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/). +## Contribute + +If you want to contribute 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 Developers Slack**: `#lambda-powertools` - **[Invite, if you don't have an account](https://join.slack.com/t/awsdevelopers/shared_invite/zt-yryddays-C9fkWrmguDv0h2EEDzCqvw)** @@ -43,4 +75,4 @@ Each TypeScript utility is installed as standalone NPM package. ## License -This library is licensed under the MIT-0 License. See the LICENSE file. \ No newline at end of file +This library is licensed under the MIT-0 License. See the LICENSE file. diff --git a/packages/tracer/README.md b/packages/tracer/README.md index b42f7ef8a8..e802a7a8d7 100644 --- a/packages/tracer/README.md +++ b/packages/tracer/README.md @@ -1,10 +1,20 @@ # AWS Lambda Powertools for TypeScript -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 for [Python](https://github.com/awslabs/aws-lambda-powertools-python) and AWS Lambda Powertools for [Java](https://github.com/awslabs/aws-lambda-powertools-java) are also available). +A suite of utilities for AWS Lambda functions 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. +AWS Lambda Powertools for [Python](https://github.com/awslabs/aws-lambda-powertools-python) and AWS Lambda Powertools for [Java](https://github.com/awslabs/aws-lambda-powertools-java) are also available). -**[📜 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)** +**[📜 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)** | **[Serverless TypeScript Demo](https://github.com/aws-samples/serverless-typescript-demo)** -> **An AWS Developer Acceleration (DevAx) initiative by Specialist Solution Architects | aws-devax-open-source@amazon.com** +## Table of contents + +- [Features](#features) +- [Getting started](#getting-started) + - [Installation](#installation) + - [Examples](#examples) +- [Credits](#credits) +- [Connect](#connect) +- [License](#license) ## Features @@ -21,6 +31,14 @@ Find the complete project's [documentation here](https://awslabs.github.io/aws-l The AWS Lambda Powertools for 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. +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](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) @@ -32,10 +50,24 @@ Each TypeScript utility is installed as standalone NPM package. * [CDK](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk) * [SAM](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/sam) +## 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). + ## Credits * 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/). +## Contribute + +If you want to contribute 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 Developers Slack**: `#lambda-powertools` - **[Invite, if you don't have an account](https://join.slack.com/t/awsdevelopers/shared_invite/zt-yryddays-C9fkWrmguDv0h2EEDzCqvw)** From 1e1527e6a304899c2fe855e2300f9b887f0bc166 Mon Sep 17 00:00:00 2001 From: Sara Gerion Date: Tue, 19 Jul 2022 08:45:28 +0200 Subject: [PATCH 2/2] docs: add middy link, add ToC items for CTAs --- README.md | 17 ++++++++++------- docs/index.md | 7 +++---- packages/logger/README.md | 21 ++++++++++++--------- packages/metrics/README.md | 21 ++++++++++++--------- packages/tracer/README.md | 17 ++++++++++------- 5 files changed, 47 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index e802a7a8d7..5801e8be03 100644 --- a/README.md +++ b/README.md @@ -12,8 +12,11 @@ AWS Lambda Powertools for [Python](https://github.com/awslabs/aws-lambda-powerto - [Getting started](#getting-started) - [Installation](#installation) - [Examples](#examples) -- [Credits](#credits) + - [Serverless TypeScript Demo](#serverless-typescript-demo-application) +- [Contribute](#contribute) +- [Roadmap](#roadmap) - [Connect](#connect) +- [Credits](#credits) - [License](#license) ## Features @@ -50,18 +53,14 @@ Or refer to the installation guide of each utility: * [CDK](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk) * [SAM](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/sam) -## Serverless TypeScript demo application +### 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). -## Credits - -* 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/). - ## Contribute -If you want to contribute to this project, please refer to our [Contributing Guidelines](https://github.com/awslabs/aws-lambda-powertools-typescript/blob/main/CONTRIBUTING.md). +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 @@ -73,6 +72,10 @@ Help us prioritize upcoming functionalities or utilities by [upvoting existing R * **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**: aws-lambda-powertools-feedback@amazon.com +## Credits + +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/). + ## License This library is licensed under the MIT-0 License. See the LICENSE file. diff --git a/docs/index.md b/docs/index.md index af17725c4e..1fc986ce70 100644 --- a/docs/index.md +++ b/docs/index.md @@ -21,7 +21,7 @@ Core utilities such as Tracer, Logger, Metrics, and Event Handler will be availa | Utility | Description | ------------------------------------------------- | --------------------------------------------------------------------------------- -[Tracer](./core/tracer.md) | Utilities to trace Lambda function handlers, and both synchronous and asynchronous functions +[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) @@ -48,9 +48,9 @@ Or refer to the installation guide of each utility: 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](https://middy.js.org/docs/) middleware engine. Powertools offers compatible Middy middleware to make this integration seamless. +* **Method decorator**. Use [TypeScript method decorators](https://www.typescriptlang.org/docs/handbook/decorators.html#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](https://www.typescriptlang.org/docs/handbook/classes.html). -* **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](https://www.typescriptlang.org/docs/handbook/decorators.html#method-decorators) if you prefer writing your business logic using TypeScript Classes. If you aren’t using Classes, this requires the most significant refactoring. ## Environment variables @@ -67,7 +67,6 @@ You can instrument your code with Powertools in three different ways: | **POWERTOOLS_TRACER_CAPTURE_HTTPS_REQUESTS** | Captures HTTP(s) requests as segments. | [Tracer](./core/tracer) | `true` | | **POWERTOOLS_LOGGER_LOG_EVENT** | Logs incoming event | [Logger](./core/logger) | `false` | | **POWERTOOLS_LOGGER_SAMPLE_RATE** | Debug log sampling | [Logger](./core/logger) | `0` | -| **POWERTOOLS_LOGGER_LOG_EVENT** | Logs incoming events | [Logger](./core/logger) | `false` | | **LOG_LEVEL** | Sets logging level | [Logger](./core/logger) | `INFO` | ## Examples diff --git a/packages/logger/README.md b/packages/logger/README.md index 6ad974300d..5801e8be03 100644 --- a/packages/logger/README.md +++ b/packages/logger/README.md @@ -10,10 +10,13 @@ AWS Lambda Powertools for [Python](https://github.com/awslabs/aws-lambda-powerto - [Features](#features) - [Getting started](#getting-started) - - [Installation](#installation) - - [Examples](#examples) -- [Credits](#credits) + - [Installation](#installation) + - [Examples](#examples) + - [Serverless TypeScript Demo](#serverless-typescript-demo-application) +- [Contribute](#contribute) +- [Roadmap](#roadmap) - [Connect](#connect) +- [Credits](#credits) - [License](#license) ## Features @@ -50,18 +53,14 @@ Or refer to the installation guide of each utility: * [CDK](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk) * [SAM](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/sam) -## Serverless TypeScript demo application +### 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). -## Credits - -* 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/). - ## Contribute -If you want to contribute to this project, please refer to our [Contributing Guidelines](https://github.com/awslabs/aws-lambda-powertools-typescript/blob/main/CONTRIBUTING.md). +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 @@ -73,6 +72,10 @@ Help us prioritize upcoming functionalities or utilities by [upvoting existing R * **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**: aws-lambda-powertools-feedback@amazon.com +## Credits + +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/). + ## License This library is licensed under the MIT-0 License. See the LICENSE file. diff --git a/packages/metrics/README.md b/packages/metrics/README.md index 6ad974300d..5801e8be03 100644 --- a/packages/metrics/README.md +++ b/packages/metrics/README.md @@ -10,10 +10,13 @@ AWS Lambda Powertools for [Python](https://github.com/awslabs/aws-lambda-powerto - [Features](#features) - [Getting started](#getting-started) - - [Installation](#installation) - - [Examples](#examples) -- [Credits](#credits) + - [Installation](#installation) + - [Examples](#examples) + - [Serverless TypeScript Demo](#serverless-typescript-demo-application) +- [Contribute](#contribute) +- [Roadmap](#roadmap) - [Connect](#connect) +- [Credits](#credits) - [License](#license) ## Features @@ -50,18 +53,14 @@ Or refer to the installation guide of each utility: * [CDK](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk) * [SAM](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/sam) -## Serverless TypeScript demo application +### 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). -## Credits - -* 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/). - ## Contribute -If you want to contribute to this project, please refer to our [Contributing Guidelines](https://github.com/awslabs/aws-lambda-powertools-typescript/blob/main/CONTRIBUTING.md). +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 @@ -73,6 +72,10 @@ Help us prioritize upcoming functionalities or utilities by [upvoting existing R * **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**: aws-lambda-powertools-feedback@amazon.com +## Credits + +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/). + ## License This library is licensed under the MIT-0 License. See the LICENSE file. diff --git a/packages/tracer/README.md b/packages/tracer/README.md index e802a7a8d7..5801e8be03 100644 --- a/packages/tracer/README.md +++ b/packages/tracer/README.md @@ -12,8 +12,11 @@ AWS Lambda Powertools for [Python](https://github.com/awslabs/aws-lambda-powerto - [Getting started](#getting-started) - [Installation](#installation) - [Examples](#examples) -- [Credits](#credits) + - [Serverless TypeScript Demo](#serverless-typescript-demo-application) +- [Contribute](#contribute) +- [Roadmap](#roadmap) - [Connect](#connect) +- [Credits](#credits) - [License](#license) ## Features @@ -50,18 +53,14 @@ Or refer to the installation guide of each utility: * [CDK](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk) * [SAM](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/sam) -## Serverless TypeScript demo application +### 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). -## Credits - -* 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/). - ## Contribute -If you want to contribute to this project, please refer to our [Contributing Guidelines](https://github.com/awslabs/aws-lambda-powertools-typescript/blob/main/CONTRIBUTING.md). +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 @@ -73,6 +72,10 @@ Help us prioritize upcoming functionalities or utilities by [upvoting existing R * **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**: aws-lambda-powertools-feedback@amazon.com +## Credits + +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/). + ## License This library is licensed under the MIT-0 License. See the LICENSE file.