From c1bf3b3bde0d201050aac564f90a8d9158d91572 Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Tue, 20 Jun 2023 14:37:24 +0200 Subject: [PATCH 1/3] fix: add back code copy button --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index b1f2e7fc4e..a0d03992e6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -43,6 +43,7 @@ theme: - navigation.indexes - navigation.tracking - content.code.annotate + - content.code.copy - toc.follow - toc.integrate - announce.dismiss From cbddc6c05a3784ffd3f039b1ca7c255638ef8863 Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Tue, 20 Jun 2023 14:41:18 +0200 Subject: [PATCH 2/3] chore: clarify instrument clients --- docs/snippets/tracer/captureAWS.ts | 5 ++++- docs/snippets/tracer/captureAWSAll.ts | 6 ++++++ docs/snippets/tracer/captureAWSv3.ts | 5 ++++- 3 files changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/snippets/tracer/captureAWS.ts b/docs/snippets/tracer/captureAWS.ts index 0f86993e15..b96c0eeb1e 100644 --- a/docs/snippets/tracer/captureAWS.ts +++ b/docs/snippets/tracer/captureAWS.ts @@ -2,4 +2,7 @@ import { S3 } from 'aws-sdk'; import { Tracer } from '@aws-lambda-powertools/tracer'; const tracer = new Tracer({ serviceName: 'serverlessAirline' }); -tracer.captureAWSClient(new S3()); +// Instrument the AWS SDK client +const client = tracer.captureAWSClient(new S3()); + +export default client; diff --git a/docs/snippets/tracer/captureAWSAll.ts b/docs/snippets/tracer/captureAWSAll.ts index bc4d4875e7..5680bec1be 100644 --- a/docs/snippets/tracer/captureAWSAll.ts +++ b/docs/snippets/tracer/captureAWSAll.ts @@ -2,4 +2,10 @@ import { Tracer } from '@aws-lambda-powertools/tracer'; import AWS from 'aws-sdk'; const tracer = new Tracer({ serviceName: 'serverlessAirline' }); + +// Instrument all AWS SDK clients created from this point onwards tracer.captureAWS(AWS); + +// Create a new client which will be automatically instrumented +const client = new AWS.SecretsManager(); +export default client; diff --git a/docs/snippets/tracer/captureAWSv3.ts b/docs/snippets/tracer/captureAWSv3.ts index f6f0d59a8f..a91bebe16b 100644 --- a/docs/snippets/tracer/captureAWSv3.ts +++ b/docs/snippets/tracer/captureAWSv3.ts @@ -2,4 +2,7 @@ import { SecretsManagerClient } from '@aws-sdk/client-secrets-manager'; import { Tracer } from '@aws-lambda-powertools/tracer'; const tracer = new Tracer({ serviceName: 'serverlessAirline' }); -tracer.captureAWSv3Client(new SecretsManagerClient({})); +// Instrument the AWS SDK client +const client = tracer.captureAWSv3Client(new SecretsManagerClient({})); + +export default client; From 886289d7266e2744a0aaf16124a4969deaff2946 Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Tue, 20 Jun 2023 17:36:13 +0200 Subject: [PATCH 3/3] docs: update middy info --- docs/core/logger.md | 9 ++++++--- docs/core/metrics.md | 9 ++++++--- docs/core/tracer.md | 12 ++++-------- docs/index.md | 2 +- docs/snippets/tracer/middy.ts | 2 +- 5 files changed, 18 insertions(+), 16 deletions(-) diff --git a/docs/core/logger.md b/docs/core/logger.md index 8707da5580..7dcdf04eff 100644 --- a/docs/core/logger.md +++ b/docs/core/logger.md @@ -108,9 +108,9 @@ This functionality will include the following keys in your structured logs: === "Middy Middleware" - !!! tip "Using Middy for the first time?" - You can install Middy by running `npm i @middy/core`. - Learn more about [its usage and lifecycle in the official Middy documentation](https://middy.js.org/docs/intro/getting-started){target="_blank"}. + !!! tip "A note about Middy" + Currently we support only Middy `v3.x` that you can install it by running `npm i @middy/core@~3`. + Check their docs to learn more about [Middy and its middleware stack](https://middy.js.org/docs/intro/getting-started){target="_blank"} as well as [best practices when working with Powertools](https://middy.js.org/docs/integrations/lambda-powertools#best-practices){target="_blank"}. ```typescript hl_lines="1 13" --8<-- "docs/snippets/logger/middy.ts" @@ -118,6 +118,9 @@ This functionality will include the following keys in your structured logs: === "Decorator" + !!! info + Decorators can only be attached to a class declaration, method, accessor, property, or parameter. Therefore, if you prefer to write your handler as a standard function rather than a Class method, use the middleware or the manual instrumentation instead. See the [official TypeScript documentation](https://www.typescriptlang.org/docs/handbook/decorators.html) for more details. + ```typescript hl_lines="8" --8<-- "docs/snippets/logger/decorator.ts" ``` diff --git a/docs/core/metrics.md b/docs/core/metrics.md index c5ebd0fb93..9d1366ad4b 100644 --- a/docs/core/metrics.md +++ b/docs/core/metrics.md @@ -195,9 +195,9 @@ You can add default dimensions to your metrics by passing them as parameters in === "Middy middleware" - !!! tip "Using Middy for the first time?" - You can install Middy by running `npm i @middy/core`. - Learn more about [its usage and lifecycle in the official Middy documentation](https://middy.js.org/docs/intro/getting-started){target="_blank"}. + !!! tip "A note about Middy" + Currently we support only Middy `v3.x` that you can install it by running `npm i @middy/core@~3`. + Check their docs to learn more about [Middy and its middleware stack](https://middy.js.org/docs/intro/getting-started){target="_blank"} as well as [best practices when working with Powertools](https://middy.js.org/docs/integrations/lambda-powertools#best-practices){target="_blank"}. ```typescript hl_lines="24-26" --8<-- "docs/snippets/metrics/defaultDimensionsMiddy.ts" @@ -211,6 +211,9 @@ You can add default dimensions to your metrics by passing them as parameters in === "with logMetrics decorator" + !!! info + Decorators can only be attached to a class declaration, method, accessor, property, or parameter. Therefore, if you prefer to write your handler as a standard function rather than a Class method, use the middleware or the manual instrumentation instead. See the [official TypeScript documentation](https://www.typescriptlang.org/docs/handbook/decorators.html) for more details. + ```typescript hl_lines="12" --8<-- "docs/snippets/metrics/defaultDimensionsDecorator.ts" ``` diff --git a/docs/core/tracer.md b/docs/core/tracer.md index 774ad26f30..b70aadb867 100644 --- a/docs/core/tracer.md +++ b/docs/core/tracer.md @@ -85,22 +85,18 @@ You can quickly start by importing the `Tracer` class, initialize it outside the === "Middy Middleware" - !!! tip "Using Middy for the first time?" - You can install Middy by running `npm i @middy/core`. - Learn more about [its usage and lifecycle in the official Middy documentation](https://middy.js.org/docs/intro/getting-started){target="_blank"}. + !!! tip "A note about Middy" + Currently we support only Middy `v3.x` that you can install it by running `npm i @middy/core@~3`. + Check their docs to learn more about [Middy and its middleware stack](https://middy.js.org/docs/intro/getting-started){target="_blank"} as well as [best practices when working with Powertools](https://middy.js.org/docs/integrations/lambda-powertools#best-practices){target="_blank"}. ```typescript hl_lines="1 14 16" --8<-- "docs/snippets/tracer/middy.ts" ``` - 1. Using Middy for the first time? You can install Middy by running `npm i @middy/core`. - Learn more about [its usage and lifecycle in the official Middy documentation](https://github.com/middyjs/middy#usage){target="_blank"}. - === "Decorator" !!! info - Decorators can only be attached to a class declaration, method, accessor, property, or parameter. Therefore, if you prefer to write your handler as a standard function rather than a Class method, use the middleware or the manual instrumentations instead. - See the [official TypeScript documentation](https://www.typescriptlang.org/docs/handbook/decorators.html) for more details. + Decorators can only be attached to a class declaration, method, accessor, property, or parameter. Therefore, if you prefer to write your handler as a standard function rather than a Class method, use the middleware or the manual instrumentation instead. See the [official TypeScript documentation](https://www.typescriptlang.org/docs/handbook/decorators.html) for more details. ```typescript hl_lines="8" --8<-- "docs/snippets/tracer/decorator.ts" diff --git a/docs/index.md b/docs/index.md index 049bd298ac..751799e719 100644 --- a/docs/index.md +++ b/docs/index.md @@ -262,7 +262,7 @@ You can include Powertools for AWS Lambda (TypeScript) Lambda Layer using [AWS L You can instrument your code with Powertools for AWS Lambda (TypeScript) 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 for AWS Lambda (TypeScript) offers compatible Middy middleware to make this integration seamless. +* **Middy** middleware. It is the best choice if your existing code base relies on the [Middy 3.x](https://middy.js.org/docs/) middleware engine. Powertools for AWS Lambda (TypeScript) 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](https://www.typescriptlang.org/docs/handbook/classes.html). 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. diff --git a/docs/snippets/tracer/middy.ts b/docs/snippets/tracer/middy.ts index e3b4f95df6..22fe705619 100644 --- a/docs/snippets/tracer/middy.ts +++ b/docs/snippets/tracer/middy.ts @@ -1,5 +1,5 @@ import { Tracer, captureLambdaHandler } from '@aws-lambda-powertools/tracer'; -import middy from '@middy/core'; // (1) +import middy from '@middy/core'; const tracer = new Tracer({ serviceName: 'serverlessAirline' });