diff --git a/docs/core/metrics.md b/docs/core/metrics.md index 99ba6dbdc3..5ac28ea501 100644 --- a/docs/core/metrics.md +++ b/docs/core/metrics.md @@ -3,8 +3,6 @@ title: Metrics description: Core utility --- - - 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/). @@ -460,3 +458,32 @@ CloudWatch EMF uses the same dimensions across all your metrics. Use `singleMetr ``` 1. Binding your handler method allows your handler to access `this` within the class methods. + +## Testing your code + +When unit testing your code that uses the `Metrics` utility, you may want to silence the logs emitted by the utility or assert that metrics are being emitted correctly. By default, the utility manages its own `console` instance, which means that you can't easily access or mock the logs emitted by the utility. + +To make it easier to test your code, you can set the `POWERTOOLS_DEV` environment variable to `true` to instruct the utility to use the global `console` object instead of its own. + +This allows you to spy on the logs emitted by the utility and assert that the metrics are being emitted correctly. + +```typescript title="Spying on emitted metrics" +describe('Metrics tests', () => { + beforeAll(() => { + process.env.POWERTOOLS_DEV = 'true'; + }) + + it('function metrics properly', async () => { + // Prepare + const metricsSpy = jest.spyOn(console, 'log').mockImplementation(); + + // Act & Assess + }); +}); +``` + +When running your tests with both [Jest](https://jestjs.io) and [Vitest](http://vitest.dev), you can use the `--silent` flag to silence the logs emitted by the utility. + +```bash title="Disabling logs while testing" +export POWERTOOLS_DEV=true && npx vitest --silent +``` diff --git a/docs/index.md b/docs/index.md index e9fcc7b2db..a5538408b0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -89,7 +89,7 @@ You can use Powertools for AWS Lambda (TypeScript) by installing it with your fa const powertoolsLayer = LayerVersion.fromLayerVersionArn( this, 'PowertoolsLayer', - `arn:aws:lambda:${Stack.of(this).region}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:3` + `arn:aws:lambda:${Stack.of(this).region}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:5` ); new Function(this, 'Function', { @@ -103,7 +103,7 @@ You can use Powertools for AWS Lambda (TypeScript) by installing it with your fa } ``` - If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools` from being bundled since the packages will be already present the Layer: + If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools/*` and `@aws-sdk/*` from being bundled since the packages are already present the layer: ```typescript new NodejsFunction(this, 'Function', { @@ -129,7 +129,7 @@ You can use Powertools for AWS Lambda (TypeScript) by installing it with your fa - !Sub arn:aws:lambda:${AWS::Region}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:5 ``` - If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools` from being bundled since the packages will be already present the Layer: + If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools/*` and `@aws-sdk/*` from being bundled since the packages are already present the layer: ```yaml hl_lines="5-14" MyLambdaFunction: @@ -142,10 +142,8 @@ You can use Powertools for AWS Lambda (TypeScript) by installing it with your fa BuildProperties: Minify: true External: - - '@aws-lambda-powertools/commons' - - '@aws-lambda-powertools/logger' - - '@aws-lambda-powertools/metrics' - - '@aws-lambda-powertools/tracer' + - '@aws-lambda-powertools/*' + - '@aws-sdk/*' ``` Check the [documentation](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-using-build-typescript.html) for more details. @@ -160,16 +158,14 @@ You can use Powertools for AWS Lambda (TypeScript) by installing it with your fa - arn:aws:lambda:${aws:region}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:5 ``` - If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools` from being bundled since the packages will be already present the Layer: + If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools/*` and `@aws-sdk/*` from being bundled since the packages are already present the layer: ```yaml custom: esbuild: external: - - '@aws-lambda-powertools/commons' - - '@aws-lambda-powertools/logger' - - '@aws-lambda-powertools/metrics' - - '@aws-lambda-powertools/tracer' + - '@aws-lambda-powertools/*' + - '@aws-sdk/*' ``` Check the [documentation](https://floydspace.github.io/serverless-esbuild/) for more details. @@ -193,7 +189,7 @@ You can use Powertools for AWS Lambda (TypeScript) by installing it with your fa function_name = "lambda_function_name" role = ... handler = "index.handler" - runtime = "nodejs16.x" + runtime = "nodejs20.x" layers = ["arn:aws:lambda:{aws::region}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:5"] source_code_hash = filebase64sha256("lambda_function_payload.zip") } @@ -218,7 +214,7 @@ You can use Powertools for AWS Lambda (TypeScript) by installing it with your fa tracingConfig: { mode: 'Active' }, - runtime: aws.lambda.Runtime.NodeJS16dX, + runtime: aws.lambda.Runtime.NodeJS20dX, handler: 'index.handler', role: role.arn, architectures: ['x86_64'] diff --git a/docs/overrides/main.html b/docs/overrides/main.html index 67010de9bc..55f86b6188 100644 --- a/docs/overrides/main.html +++ b/docs/overrides/main.html @@ -8,6 +8,6 @@ {% endblock %} {% block announce %} -Version 2 is generally available 🔥 Check out the upgrade guide to see -what's new. +Starting from July 1, 2024 we will end support for Node.js 16. Learn more here. {% endblock %} \ No newline at end of file diff --git a/docs/upgrade.md b/docs/upgrade.md index a79384a996..af4485814e 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -173,6 +173,27 @@ In v2, you can now directly import from the `types` subpath export, e.g., `@aws- import { LogAttributes, UnformattedAttributes } from '@aws-lambda-powertools/logger/types'; ``` +### Using eslint? + +When using `eslint`, you might need to use [`@typescript-eslint/parser`](https://github.com/typescript-eslint/typescript-eslint/tree/HEAD/packages/parser) and [`eslint-plugin-import`](https://www.npmjs.com/package/eslint-import-resolver-typescript) to resolve the new subpath imports. + +Below is an example of how to configure your `.eslintrc.json` file: + +```json +{ + "parser": "@typescript-eslint/parser", + "settings": { + "import/resolver": { + "node": {}, + "typescript": { + "project": "./tsconfig.json", + "alwaysTryTypes": true, + }, + }, + }, +} +``` + ## Logger ### Log sampling