docs(metrics): review API docs & README (#2983)

Author: am29d

packages/idempotency/README.md

@@ -1,10 +1,25 @@
-# Powertools for AWS Lambda (TypeScript) - Idempotency Utility
+# Powertools for AWS Lambda (TypeScript) - Idempotency Utility <!-- omit in toc -->
 
 Powertools for AWS Lambda (TypeScript) is a developer toolkit to implement
 Serverless [best practices and increase developer velocity](https://docs.powertools.aws.dev/lambda/typescript/latest/#features).
 
 You can use the package in both TypeScript and JavaScript code bases.
 
+- [Intro](#intro)
+- [Usage](#usage)
+    - [Function wrapper](#function-wrapper)
+    - [Decorator](#decorator)
+    - [Middy middleware](#middy-middleware)
+    - [DynamoDB persistence layer](#dynamodb-persistence-layer)
+- [Contribute](#contribute)
+- [Roadmap](#roadmap)
+- [Connect](#connect)
+- [How to support Powertools for AWS Lambda (TypeScript)?](#how-to-support-powertools-for-aws-lambda-typescript)
+    - [Becoming a reference customer](#becoming-a-reference-customer)
+    - [Sharing your work](#sharing-your-work)
+    - [Using Lambda Layer](#using-lambda-layer)
+- [License](#license)
+
 ## Intro
 
 This package provides a utility to implement idempotency in your Lambda functions.

packages/metrics/README.md

@@ -4,69 +4,167 @@ Powertools for AWS Lambda (TypeScript) is a developer toolkit to implement Serve
 
 You can use the library in both TypeScript and JavaScript code bases.
 
-> Also available in [Python](https://github.com/aws-powertools/powertools-lambda-python), [Java](https://github.com/aws-powertools/powertools-lambda-java), and [.NET](https://github.com/aws-powertools/powertools-lambda-dotnet).
-
-**[Documentation](https://docs.powertools.aws.dev/lambda/typescript/)** | **[npm](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Roadmap](https://docs.powertools.aws.dev/lambda/typescript/latest/roadmap)** | **[Examples](https://github.com/aws-powertools/powertools-lambda-typescript/tree/main/examples)** | **[Serverless TypeScript Demo](https://github.com/aws-samples/serverless-typescript-demo)**
-
-## Table of contents <!-- omit in toc -->
-
-- [Features](#features)
-- [Getting started](#getting-started)
-    - [Installation](#installation)
-    - [Examples](#examples)
-    - [Demo applications](#demo-applications)
+- [Intro](#intro)
+- [Usage](#usage)
+    - [Basic usage](#basic-usage)
+    - [Flushing metrics](#flushing-metrics)
+    - [Capturing cold start as a metric](#capturing-cold-start-as-a-metric)
+    - [Adding metadata](#adding-metadata)
 - [Contribute](#contribute)
 - [Roadmap](#roadmap)
 - [Connect](#connect)
 - [How to support Powertools for AWS Lambda (TypeScript)?](#how-to-support-powertools-for-aws-lambda-typescript)
     - [Becoming a reference customer](#becoming-a-reference-customer)
     - [Sharing your work](#sharing-your-work)
     - [Using Lambda Layer](#using-lambda-layer)
-- [Credits](#credits)
 - [License](#license)
 
-## Features
+## Intro
+
+## Usage
+
+To get started, install the library by running:
+
+```sh
+npm i @aws-lambda-powertools/metrics
+```
+
+### Basic usage
 
-- **[Tracer](https://docs.powertools.aws.dev/lambda/typescript/latest/core/tracer/)** - Utilities to trace Lambda function handlers, and both synchronous and asynchronous functions
-- **[Logger](https://docs.powertools.aws.dev/lambda/typescript/latest/core/logger/)** - Structured logging made easier, and a middleware to enrich log items with key details of the Lambda context
-- **[Metrics](https://docs.powertools.aws.dev/lambda/typescript/latest/core/metrics/)** - Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF)
-- **[Parameters](https://docs.powertools.aws.dev/lambda/typescript/latest/utilities/parameters/)** - High-level functions to retrieve one or more parameters from AWS SSM, Secrets Manager, AppConfig, and DynamoDB
+The library provides a utility function to emit metrics to CloudWatch using [Embedded Metric Format (EMF)](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format.html).
 
-## Getting started
+```ts
+import { MetricUnit, Metrics } from '@aws-lambda-powertools/metrics';
 
-Find the complete project's [documentation here](https://docs.powertools.aws.dev/lambda/typescript).
+const metrics = new Metrics({
+  namespace: 'serverlessAirline',
+  serviceName: 'orders',
+});
 
-### Installation
+export const handler = async (
+  _event: unknown,
+  _context: unknown
+): Promise<void> => {
+  metrics.addMetric('successfulBooking', MetricUnit.Count, 1);
+};
+```
+
+### Flushing metrics
+
+As you finish adding all your metrics, you need to serialize and "flush them" by calling publishStoredMetrics(). This will print the metrics to standard output.
+
+You can flush metrics automatically using one of the following methods:
 
-The Powertools for AWS Lambda (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.
+- manually by calling `publishStoredMetrics()` at the end of your Lambda function
 
-Install all three core utilities at once with this single command:
+```ts
+import { MetricUnit, Metrics } from '@aws-lambda-powertools/metrics';
 
-```shell
-npm install @aws-lambda-powertools/logger @aws-lambda-powertools/tracer @aws-lambda-powertools/metrics
+const metrics = new Metrics({
+  namespace: 'serverlessAirline',
+  serviceName: 'orders',
+});
+
+export const handler = async (
+  _event: unknown,
+  _context: unknown
+): Promise<void> => {
+  metrics.addMetric('successfulBooking', MetricUnit.Count, 1);
+  metrics.publishStoredMetrics();
+};
 ```
 
-Or refer to the installation guide of each utility:
+- middy compatible middleware `logMetrics()`
+
+```ts
+import { MetricUnit, Metrics } from '@aws-lambda-powertools/metrics';
+import { logMetrics } from '@aws-lambda-powertools/metrics/middleware';
+import middy from '@middy/core';
 
-👉 [Installation guide for the **Tracer** utility](https://docs.powertools.aws.dev/lambda/typescript/latest/core/tracer#getting-started)
+const metrics = new Metrics({
+  namespace: 'serverlessAirline',
+  serviceName: 'orders',
+});
 
-👉 [Installation guide for the **Logger** utility](https://docs.powertools.aws.dev/lambda/typescript/latest/core/logger#getting-started)
+const lambdaHandler = async (
+  _event: unknown,
+  _context: unknown
+): Promise<void> => {
+  metrics.addMetric('successfulBooking', MetricUnit.Count, 1);
+};
 
-👉 [Installation guide for the **Metrics** utility](https://docs.powertools.aws.dev/lambda/typescript/latest/core/metrics#getting-started)
+export const handler = middy(lambdaHandler).use(logMetrics(metrics));
+```
 
-👉 [Installation guide for the **Parameters** utility](https://docs.powertools.aws.dev/lambda/typescript/latest/utilities/parameters/#getting-started)
+- using decorator `@logMetrics()`
 
-### Examples
+```ts
+import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';
+import { MetricUnit, Metrics } from '@aws-lambda-powertools/metrics';
 
-You can find examples of how to use Powertools for AWS Lambda (TypeScript) in the [examples](https://github.com/aws-powertools/powertools-lambda-typescript/tree/main/examples/app) directory. The application is a simple REST API that can be deployed via either AWS CDK or AWS SAM.
+const metrics = new Metrics({
+  namespace: 'serverlessAirline',
+  serviceName: 'orders',
+});
 
-### Demo applications
+class Lambda implements LambdaInterface {
+  @metrics.logMetrics()
+  public async handler(_event: unknown, _context: unknown): Promise<void> {
+    metrics.addMetric('successfulBooking', MetricUnit.Count, 1);
+  }
+}
 
-The [Serverless TypeScript Demo](https://github.com/aws-samples/serverless-typescript-demo) shows how to use Powertools for AWS Lambda (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).
+const handlerClass = new Lambda();
+export const handler = handlerClass.handler.bind(handlerClass); 
+```
 
-The [AWS Lambda performance tuning](https://github.com/aws-samples/optimizations-for-lambda-functions) repository also uses Powertools for AWS Lambda (TypeScript) as well as demonstrating other performance tuning techniques for Lambda functions written in TypeScript.
+Using the Middy middleware or decorator will automatically validate, serialize, and flush all your metrics.
+
+### Capturing cold start as a metric
+
+You can optionally capture cold start metrics with the logMetrics middleware or decorator via the captureColdStartMetric param.
+
+```ts
+import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';
+import { MetricUnit, Metrics } from '@aws-lambda-powertools/metrics';
+
+const metrics = new Metrics({
+  namespace: 'serverlessAirline',
+  serviceName: 'orders',
+});
+
+export class MyFunction implements LambdaInterface {
+  @metrics.logMetrics({ captureColdStartMetric: true })
+  public async handler(_event: unknown, _context: unknown): Promise<void> {
+    metrics.addMetric('successfulBooking', MetricUnit.Count, 1);
+  }
+}
+```
+
+### Adding metadata
+
+You can add high-cardinality data as part of your Metrics log with the `addMetadata` method. This is useful when you want to search highly contextual information along with your metrics in your logs.
+
+```ts
+import { MetricUnit, Metrics } from '@aws-lambda-powertools/metrics';
+import { logMetrics } from '@aws-lambda-powertools/metrics/middleware';
+import middy from '@middy/core';
+
+const metrics = new Metrics({
+  namespace: 'serverlessAirline',
+  serviceName: 'orders',
+});
+
+const lambdaHandler = async (
+  _event: unknown,
+  _context: unknown
+): Promise<void> => {
+  metrics.addMetric('successfulBooking', MetricUnit.Count, 1);
+  metrics.addMetadata('bookingId', '7051cd10-6283-11ec-90d6-0242ac120003');
+};
+
+export const handler = middy(lambdaHandler).use(logMetrics(metrics));
+```
 
 ## Contribute
 
@@ -86,7 +184,10 @@ Help us prioritize upcoming functionalities or utilities by [upvoting existing R
 
 ### Becoming a reference customer
 
-Knowing which companies are using this library is important to help prioritize the project internally. If your company is using Powertools for AWS Lambda (TypeScript), you can request to have your name and logo added to the README file by raising a [Support Powertools for AWS Lambda (TypeScript) (become a reference)](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=customer-reference&template=support_powertools.yml&title=%5BSupport+Lambda+Powertools%5D%3A+%3Cyour+organization+name%3E) issue.
+Knowing which companies are using this library is important to help prioritize the project internally. If your company
+is using Powertools for AWS Lambda (TypeScript), you can request to have your name and logo added to the README file by
+raising a [Support Powertools for AWS Lambda (TypeScript) (become a reference)](https://s12d.com/become-reference-pt-ts)
+issue.
 
 The following companies, among others, use Powertools:
 
@@ -112,11 +213,7 @@ Share what you did with Powertools for AWS Lambda (TypeScript) 💞💞. Blog po
 
 ### Using Lambda Layer
 
-This helps us understand who uses Powertools for AWS Lambda (TypeScript) in a non-intrusive way, and helps us gain future investments for other Powertools for AWS Lambda languages. When [using Layers](#lambda-layers), you can add Powertools for AWS Lambda (TypeScript) as a dev dependency (or as part of your virtual env) to not impact the development process.
-
-## Credits
-
-Credits for the Powertools for AWS Lambda (TypeScript) idea go to [DAZN](https://github.com/getndazn) and their [DAZN Lambda Powertools](https://github.com/getndazn/dazn-lambda-powertools/).
+This helps us understand who uses Powertools for AWS Lambda (TypeScript) in a non-intrusive way, and helps us gain future investments for other Powertools for AWS Lambda languages. When [using Layers](https://docs.powertools.aws.dev/lambda/typescript/latest/#lambda-layer), you can add Powertools as a dev dependency to not impact the development process.
 
 ## License