From 13e5bf249906a10cc40bbe543594620ef5d46df7 Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Wed, 29 Dec 2021 12:34:13 +0100 Subject: [PATCH 1/9] docs: improve contrast for inline code expressions --- docs/stylesheets/extra.css | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 0d37af692c..e20bffa139 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -38,3 +38,7 @@ cursor: pointer; border-bottom: 0.1px dashed black; } + +p code { + font-weight: bolder; +} \ No newline at end of file From fc5e29da17cafc982b6097592e7060f6beab91a8 Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Wed, 29 Dec 2021 12:35:38 +0100 Subject: [PATCH 2/9] docs: format stylesheet & remove invalid declarations --- docs/stylesheets/extra.css | 22 +++++++--------------- 1 file changed, 7 insertions(+), 15 deletions(-) diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index e20bffa139..429ee3416c 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -1,37 +1,29 @@ .md-grid { - max-width: 81vw -} - -.highlight .hll { - background-color: lavender - - [data-md-color-scheme="slate"] { - background-color: rgb(69, 48, 164) - } + max-width: 81vw; } .md-typeset table:not([class]) { - font-size: 0.75rem + font-size: 0.75rem; } .md-typeset a { - border-bottom: 0.1px dashed black + border-bottom: 0.1px dashed black; } .md-typeset table:not([class]) { - font-size: 0.75rem + font-size: 0.75rem; } .md-nav__link--active { - font-weight: bold + font-weight: bold; } .md-typeset .admonition, .md-typeset details { - font-size: 0.70rem + font-size: 0.70rem; } [data-md-color-scheme="slate"] { - --md-typeset-a-color: rgb(28, 152, 152) + --md-typeset-a-color: rgb(28, 152, 152); } .copyMe { From e439de3dbd5e062656bbd2722b881d852b7818b2 Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Wed, 29 Dec 2021 12:38:17 +0100 Subject: [PATCH 3/9] docs: fix typo in connect section --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index df0880fc40..173a38019d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -78,5 +78,5 @@ Each TypeScript utility is installed as standalone NPM package. ## 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){target="_blank"}** +* **AWS Developers Slack**: `#lambda-powertools` - [Invite, if you don't have an account](https://join.slack.com/t/awsdevelopers/shared_invite/zt-yryddays-C9fkWrmguDv0h2EEDzCqvw){target="_blank"} * **Email**: aws-lambda-powertools-feedback@amazon.com From 649996c16e41c707673c98a56127fc49592132fa Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Wed, 29 Dec 2021 12:57:24 +0100 Subject: [PATCH 4/9] docs: clarified middy's usage & linked to official docs --- docs/core/logger.md | 6 ++++++ docs/core/metrics.md | 6 ++++++ docs/core/tracer.md | 8 +++++++- 3 files changed, 19 insertions(+), 1 deletion(-) diff --git a/docs/core/logger.md b/docs/core/logger.md index 3966afa396..1d4d7e797b 100644 --- a/docs/core/logger.md +++ b/docs/core/logger.md @@ -179,6 +179,12 @@ In each case, the printed log will look like this: } ``` +!!! note + Middy comes bundled with Logger, so you can just import it when using the middleware. + +!!! tip "Using Middy for the first time?" + Learn more about [its usage and lifecycle in the official Middy documentation](https://github.com/middyjs/middy#usage){target="_blank"}. + ### 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: diff --git a/docs/core/metrics.md b/docs/core/metrics.md index 9cb97c6be4..77628493cb 100644 --- a/docs/core/metrics.md +++ b/docs/core/metrics.md @@ -141,6 +141,12 @@ You can use add default dimensions to your metrics by passing them as parameters * using the `setDefaultDimensions` method * in the decorator +!!! note + Middy comes bundled with Metrics, so you can just import it when using the middleware. + +!!! tip "Using Middy for the first time?" + Learn more about [its usage and lifecycle in the official Middy documentation](https://github.com/middyjs/middy#usage){target="_blank"}. + If you'd like to remove them at some point, you can use `clearDefaultDimensions` method. See examples below: diff --git a/docs/core/tracer.md b/docs/core/tracer.md index e2d8b1ca85..9a412c3831 100644 --- a/docs/core/tracer.md +++ b/docs/core/tracer.md @@ -105,7 +105,7 @@ You can quickly start by importing the `Tracer` class, initialize it outside the === "Manual" - ```typescript hl_lines="1 3 7 9 11 17 20 24" + ```typescript hl_lines="1 3 7 9-10 13-14 20 23 27 29" import { Tracer } from '@aws-lambda-powertools/tracer'; const tracer = Tracer(); // Sets service via env var @@ -148,6 +148,12 @@ When using the `captureLambdaHandler` decorator or middleware, Tracer performs t * Creates a `ServiceName` annotation to easily filter traces that have a specific service name * Captures any response, or full exceptions generated by the handler, and include as tracing metadata +!!! note + Middy comes bundled with Tracer, so you can just import it when using the middleware. + +!!! tip "Using Middy for the first time?" + Learn more about [its usage and lifecycle in the official Middy documentation](https://github.com/middyjs/middy#usage){target="_blank"}. + ### Annotations & Metadata **Annotations** are key-values associated with traces and indexed by AWS X-Ray. You can use them to filter traces and to create [Trace Groups](https://aws.amazon.com/about-aws/whats-new/2018/11/aws-xray-adds-the-ability-to-group-traces/) to slice and dice your transactions. From 7f17f444f71f74cc7a4971111b5dc0597454bd2f Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Wed, 29 Dec 2021 13:03:39 +0100 Subject: [PATCH 5/9] docs: uniformed main example with tabs for logger --- docs/core/logger.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/docs/core/logger.md b/docs/core/logger.md index 1d4d7e797b..59c6a3a367 100644 --- a/docs/core/logger.md +++ b/docs/core/logger.md @@ -105,11 +105,9 @@ Key | Example **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: +=== "Middleware" -=== "handler.ts" - - ```typescript hl_lines="1 9-11" + ```typescript hl_lines="1-2 10-11" import { Logger, injectLambdaContext } from "@aws-lambda-powertools/logger"; import middy from '@middy/core'; @@ -123,9 +121,7 @@ Key | Example .use(injectLambdaContext(logger)); ``` -#### Method 2, calling the `addContext` method: - -=== "handler.ts" +=== "Manual" ```typescript hl_lines="7" import { Logger } from "@aws-lambda-powertools/logger"; @@ -141,9 +137,7 @@ Key | Example }; ``` -#### Method 3, using a class decorator: - -=== "handler.ts" +=== "Decorator" ```typescript hl_lines="7" import { Logger } from "@aws-lambda-powertools/logger"; From 28a1261a8236ffccd39db7755b0df985473e742c Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Wed, 29 Dec 2021 13:05:10 +0100 Subject: [PATCH 6/9] docs: moved aws sdk patching under getting started section --- docs/core/tracer.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/tracer.md b/docs/core/tracer.md index 9a412c3831..dfb4456c3f 100644 --- a/docs/core/tracer.md +++ b/docs/core/tracer.md @@ -258,8 +258,6 @@ You can trace other methods using the `captureMethod` decorator or manual instru } ``` -## Advanced - ### Patching AWS SDK clients Tracer can patch [AWS SDK clients](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-awssdkclients.html) and create traces when your application makes calls to AWS services. @@ -306,6 +304,8 @@ If you're looking to shave a few microseconds, or milliseconds depending on your const s3 = tracer.captureAWSClient(new S3({ apiVersion: "2006-03-01" })); ``` +## Advanced + ### Disabling response auto-capture Use **`POWERTOOLS_TRACER_CAPTURE_RESPONSE=false`** environment variable to instruct Tracer **not** to serialize function responses as metadata. From 039f489d3b61971ce6de206d34796f79fe064b83 Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Wed, 29 Dec 2021 14:09:15 +0100 Subject: [PATCH 7/9] docs: added testing your code section to logger --- docs/core/logger.md | 45 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/docs/core/logger.md b/docs/core/logger.md index 59c6a3a367..91814a34cc 100644 --- a/docs/core/logger.md +++ b/docs/core/logger.md @@ -621,4 +621,47 @@ This is how the printed log would look: }, "awsAccountId": "123456789012" } - ``` \ No newline at end of file + ``` + +## Testing your code + +### Inject Lambda Context + +When unit testing your code that makes use of `logger.addContext()` or `injectLambdaContext` middleware and decorator, you can optionally pass a dummy Lambda Context if you want your logs to contain this information. + +This is a Jest sample that provides the minimum information necessary for Logger to inject context data: + +=== "handler.test.ts" + +!!! tip + If you don't want to declare your own dummy Lambda Context, you can use [`ContextExamples.helloworldContext`](https://github.com/awslabs/aws-lambda-powertools-typescript/blob/main/packages/commons/src/tests/resources/contexts/hello-world.ts#L3-L16) from [`@aws-lambda-powertools/commons`](https://www.npmjs.com/package/@aws-lambda-powertools/commons). + +```typescript + +const dummyContext = { + callbackWaitsForEmptyEventLoop: true, + functionVersion: '$LATEST', + functionName: 'foo-bar-function', + memoryLimitInMB: '128', + logGroupName: '/aws/lambda/foo-bar-function', + logStreamName: '2021/03/09/[$LATEST]abcdef123456abcdef123456abcdef123456', + invokedFunctionArn: 'arn:aws:lambda:eu-central-1:123456789012:function:foo-bar-function', + awsRequestId: 'c6af9ac6-7b61-11e6-9a41-93e812345678', + getRemainingTimeInMillis: () => 1234, + done: () => console.log('Done!'), + fail: () => console.log('Failed!'), + succeed: () => console.log('Succeeded!'), +}; + +describe('MyUnitTest', () => { + + test('Lambda invoked successfully', async () => { + + const testEvent = { test: 'test' }; + await handler(testEvent, dummyContext); + + }); + +}); + +``` \ No newline at end of file From 07837d383d2118d4fee399b586b1566897f6f376 Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Wed, 29 Dec 2021 15:28:54 +0100 Subject: [PATCH 8/9] docs: moved middy tips under middy examples --- docs/core/logger.md | 12 ++++++------ docs/core/metrics.md | 12 ++++++------ docs/core/tracer.md | 12 ++++++------ 3 files changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/core/logger.md b/docs/core/logger.md index 91814a34cc..cb41b131fd 100644 --- a/docs/core/logger.md +++ b/docs/core/logger.md @@ -107,6 +107,12 @@ Key | Example === "Middleware" + !!! note + Middy comes bundled with Logger, so you can just import it when using the middleware. + + !!! tip "Using Middy for the first time?" + Learn more about [its usage and lifecycle in the official Middy documentation](https://github.com/middyjs/middy#usage){target="_blank"}. + ```typescript hl_lines="1-2 10-11" import { Logger, injectLambdaContext } from "@aws-lambda-powertools/logger"; import middy from '@middy/core'; @@ -173,12 +179,6 @@ In each case, the printed log will look like this: } ``` -!!! note - Middy comes bundled with Logger, so you can just import it when using the middleware. - -!!! tip "Using Middy for the first time?" - Learn more about [its usage and lifecycle in the official Middy documentation](https://github.com/middyjs/middy#usage){target="_blank"}. - ### 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: diff --git a/docs/core/metrics.md b/docs/core/metrics.md index 77628493cb..9a9f906311 100644 --- a/docs/core/metrics.md +++ b/docs/core/metrics.md @@ -141,12 +141,6 @@ You can use add default dimensions to your metrics by passing them as parameters * using the `setDefaultDimensions` method * in the decorator -!!! note - Middy comes bundled with Metrics, so you can just import it when using the middleware. - -!!! tip "Using Middy for the first time?" - Learn more about [its usage and lifecycle in the official Middy documentation](https://github.com/middyjs/middy#usage){target="_blank"}. - If you'd like to remove them at some point, you can use `clearDefaultDimensions` method. See examples below: @@ -169,6 +163,12 @@ See examples below: === "Middy middleware" + !!! note + Middy comes bundled with Metrics, so you can just import it when using the middleware. + + !!! tip "Using Middy for the first time?" + Learn more about [its usage and lifecycle in the official Middy documentation](https://github.com/middyjs/middy#usage){target="_blank"}. + ```typescript hl_lines="5" import { Metrics, MetricUnits, logMetrics } from '@aws-lambda-powertools/metrics'; import { Context } from 'aws-lambda'; diff --git a/docs/core/tracer.md b/docs/core/tracer.md index dfb4456c3f..6c02b8d363 100644 --- a/docs/core/tracer.md +++ b/docs/core/tracer.md @@ -72,6 +72,12 @@ You can quickly start by importing the `Tracer` class, initialize it outside the === "Middleware" + !!! note + Middy comes bundled with Tracer, so you can just import it when using the middleware. + + !!! tip "Using Middy for the first time?" + Learn more about [its usage and lifecycle in the official Middy documentation](https://github.com/middyjs/middy#usage){target="_blank"}. + ```typescript hl_lines="1-2 4 7 9" import { Tracer } from '@aws-lambda-powertools/tracer'; import middy from '@middy/core'; @@ -148,12 +154,6 @@ When using the `captureLambdaHandler` decorator or middleware, Tracer performs t * Creates a `ServiceName` annotation to easily filter traces that have a specific service name * Captures any response, or full exceptions generated by the handler, and include as tracing metadata -!!! note - Middy comes bundled with Tracer, so you can just import it when using the middleware. - -!!! tip "Using Middy for the first time?" - Learn more about [its usage and lifecycle in the official Middy documentation](https://github.com/middyjs/middy#usage){target="_blank"}. - ### Annotations & Metadata **Annotations** are key-values associated with traces and indexed by AWS X-Ray. You can use them to filter traces and to create [Trace Groups](https://aws.amazon.com/about-aws/whats-new/2018/11/aws-xray-adds-the-ability-to-group-traces/) to slice and dice your transactions. From d763bed28c7e5406a297c111a8d8dca015635eff Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Wed, 29 Dec 2021 16:11:11 +0100 Subject: [PATCH 9/9] docs: Moved tip under code example in testing yoru code section --- docs/core/logger.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/core/logger.md b/docs/core/logger.md index cb41b131fd..39dd62e694 100644 --- a/docs/core/logger.md +++ b/docs/core/logger.md @@ -633,9 +633,6 @@ This is a Jest sample that provides the minimum information necessary for Logger === "handler.test.ts" -!!! tip - If you don't want to declare your own dummy Lambda Context, you can use [`ContextExamples.helloworldContext`](https://github.com/awslabs/aws-lambda-powertools-typescript/blob/main/packages/commons/src/tests/resources/contexts/hello-world.ts#L3-L16) from [`@aws-lambda-powertools/commons`](https://www.npmjs.com/package/@aws-lambda-powertools/commons). - ```typescript const dummyContext = { @@ -664,4 +661,7 @@ describe('MyUnitTest', () => { }); -``` \ No newline at end of file +``` + +!!! tip + If you don't want to declare your own dummy Lambda Context, you can use [`ContextExamples.helloworldContext`](https://github.com/awslabs/aws-lambda-powertools-typescript/blob/main/packages/commons/src/tests/resources/contexts/hello-world.ts#L3-L16) from [`@aws-lambda-powertools/commons`](https://www.npmjs.com/package/@aws-lambda-powertools/commons). \ No newline at end of file