From 996dba61795b526cbfc0b209119b781b80e3c488 Mon Sep 17 00:00:00 2001 From: Grzegorz Kozub Date: Wed, 5 Jan 2022 19:50:41 +0100 Subject: [PATCH 1/3] refactor(metrics): rename option property from raiseOnEmptyMetrics to throwOnEmptyMetrics --- docs/core/metrics.md | 4 ++-- .../examples/decorator/empty-metrics.ts | 4 ++-- packages/metrics/examples/empty-metrics.ts | 4 ++-- packages/metrics/src/Metrics.ts | 18 +++++++++--------- packages/metrics/src/middleware/middy.ts | 6 +++--- packages/metrics/src/types/Metrics.ts | 4 ++-- .../tests/e2e/decorator.test.MyFunction.ts | 2 +- .../e2e/standardFunctions.test.MyFunction.ts | 2 +- packages/metrics/tests/unit/Metrics.test.ts | 10 +++++----- .../tests/unit/middleware/middy.test.ts | 4 ++-- 10 files changed, 29 insertions(+), 29 deletions(-) diff --git a/docs/core/metrics.md b/docs/core/metrics.md index 5d68a1ef92..ac7ca3ee18 100644 --- a/docs/core/metrics.md +++ b/docs/core/metrics.md @@ -433,7 +433,7 @@ The `logMetrics` decorator of the metrics utility can be used when your Lambda h #### Throwing a RangeError when no metrics are emitted -If you want to ensure that at least one metric is emitted before you flush them, you can use the `raiseOnEmptyMetrics` parameter and pass it to the middleware or decorator: +If you want to ensure that at least one metric is emitted before you flush them, you can use the `throwOnEmptyMetrics` parameter and pass it to the middleware or decorator: ```typescript hl_lines="11" import { Metrics, MetricUnits, logMetrics } from '@aws-lambda-powertools/metrics'; @@ -446,7 +446,7 @@ If you want to ensure that at least one metric is emitted before you flush them, } export const handler = middy(lambdaHandler) - .use(logMetrics(metrics, { raiseOnEmptyMetrics: true })); + .use(logMetrics(metrics, { throwOnEmptyMetrics: true })); ``` ### Capturing a cold start invocation as metric diff --git a/packages/metrics/examples/decorator/empty-metrics.ts b/packages/metrics/examples/decorator/empty-metrics.ts index 91be760dc6..008e5b6182 100644 --- a/packages/metrics/examples/decorator/empty-metrics.ts +++ b/packages/metrics/examples/decorator/empty-metrics.ts @@ -16,10 +16,10 @@ const metrics = new Metrics(); class Lambda implements LambdaInterface { // Be default, we will not throw any error if there is no metrics. Use this property to override and throw an exception - @metrics.logMetrics({ raiseOnEmptyMetrics: true }) + @metrics.logMetrics({ throwOnEmptyMetrics: true }) public handler(_event: TEvent, _context: Context, _callback: Callback): void | Promise { // Notice that no metrics are added - // Since the raiseOnEmptyMetrics parameter is set to true, the Powertool throw an Error + // Since the throwOnEmptyMetrics parameter is set to true, the Powertool throw an Error } } diff --git a/packages/metrics/examples/empty-metrics.ts b/packages/metrics/examples/empty-metrics.ts index 00c6e60870..dedb0ccfc6 100644 --- a/packages/metrics/examples/empty-metrics.ts +++ b/packages/metrics/examples/empty-metrics.ts @@ -14,10 +14,10 @@ const metrics = new Metrics(); const lambdaHandler = async (): Promise => { // Notice that no metrics are added - // Since the raiseOnEmptyMetrics parameter is set to true, the Powertool throw an Error + // Since the throwOnEmptyMetrics parameter is set to true, the Powertool throw an Error }; const handlerWithMiddleware = middy(lambdaHandler) - .use(logMetrics(metrics, { raiseOnEmptyMetrics: true })); + .use(logMetrics(metrics, { throwOnEmptyMetrics: true })); handlerWithMiddleware(dummyEvent, dummyContext, () => console.log('Lambda invoked!')); \ No newline at end of file diff --git a/packages/metrics/src/Metrics.ts b/packages/metrics/src/Metrics.ts index c2fb92e49a..4b7a88e129 100644 --- a/packages/metrics/src/Metrics.ts +++ b/packages/metrics/src/Metrics.ts @@ -49,7 +49,7 @@ const DEFAULT_NAMESPACE = 'default_namespace'; * * // FYI: Decorator might not render properly in VSCode mouse over due to https://github.com/microsoft/TypeScript/issues/39371 and might show as *@metrics* instead of `@metrics.logMetrics` * - * @metrics.logMetrics({captureColdStartMetric: true, raiseOnEmptyMetrics: true, }) + * @metrics.logMetrics({captureColdStartMetric: true, throwOnEmptyMetrics: true, }) * public handler(_event: any, _context: Context, _callback: Callback): void | Promise { * // ... * metrics.addMetric('test-metric', MetricUnits.Count, 10); @@ -89,7 +89,7 @@ class Metrics implements MetricsInterface { private isSingleMetric: boolean = false; private metadata: { [key: string]: string } = {}; private namespace?: string; - private shouldRaiseOnEmptyMetrics: boolean = false; + private shouldThrowOnEmptyMetrics: boolean = false; private storedMetrics: StoredMetrics = {}; public constructor(options: MetricsOptions = {}) { @@ -227,9 +227,9 @@ class Metrics implements MetricsInterface { * @decorator Class */ public logMetrics(options: ExtraOptions = {}): HandlerMethodDecorator { - const { raiseOnEmptyMetrics, defaultDimensions, captureColdStartMetric } = options; - if (raiseOnEmptyMetrics) { - this.raiseOnEmptyMetrics(); + const { throwOnEmptyMetrics, defaultDimensions, captureColdStartMetric } = options; + if (throwOnEmptyMetrics) { + this.throwOnEmptyMetrics(); } if (defaultDimensions !== undefined) { this.setDefaultDimensions(defaultDimensions); @@ -293,13 +293,13 @@ class Metrics implements MetricsInterface { * const metrics = new Metrics({namespace:"serverlessAirline", serviceName:"orders"}); * * export const handler = async (event: any, context: Context) => { - * metrics.raiseOnEmptyMetrics(); + * metrics.throwOnEmptyMetrics(); * metrics.publishStoredMetrics(); // will throw since no metrics added. * } * ``` */ - public raiseOnEmptyMetrics(): void { - this.shouldRaiseOnEmptyMetrics = true; + public throwOnEmptyMetrics(): void { + this.shouldThrowOnEmptyMetrics = true; } /** @@ -312,7 +312,7 @@ class Metrics implements MetricsInterface { Name: metricDefinition.name, Unit: metricDefinition.unit, })); - if (metricDefinitions.length === 0 && this.shouldRaiseOnEmptyMetrics) { + if (metricDefinitions.length === 0 && this.shouldThrowOnEmptyMetrics) { throw new RangeError('The number of metrics recorded must be higher than zero'); } diff --git a/packages/metrics/src/middleware/middy.ts b/packages/metrics/src/middleware/middy.ts index 1c6948fd10..5f40c050b9 100644 --- a/packages/metrics/src/middleware/middy.ts +++ b/packages/metrics/src/middleware/middy.ts @@ -8,9 +8,9 @@ const logMetrics = (target: Metrics | Metrics[], options: ExtraOptions = {}): mi const logMetricsBefore = async (request: middy.Request): Promise => { metricsInstances.forEach((metrics: Metrics) => { metrics.setFunctionName(request.context.functionName); - const { raiseOnEmptyMetrics, defaultDimensions, captureColdStartMetric } = options; - if (raiseOnEmptyMetrics !== undefined) { - metrics.raiseOnEmptyMetrics(); + const { throwOnEmptyMetrics, defaultDimensions, captureColdStartMetric } = options; + if (throwOnEmptyMetrics !== undefined) { + metrics.throwOnEmptyMetrics(); } if (defaultDimensions !== undefined) { metrics.setDefaultDimensions(defaultDimensions); diff --git a/packages/metrics/src/types/Metrics.ts b/packages/metrics/src/types/Metrics.ts index c0bc543da1..c25653ca44 100644 --- a/packages/metrics/src/types/Metrics.ts +++ b/packages/metrics/src/types/Metrics.ts @@ -39,7 +39,7 @@ type HandlerMethodDecorator = ( * ```typescript * * const metricsOptions: MetricsOptions = { - * raiseOnEmptyMetrics: true, + * throwOnEmptyMetrics: true, * defaultDimensions: {'environment': 'dev'}, * captureColdStartMetric: true, * } @@ -51,7 +51,7 @@ type HandlerMethodDecorator = ( * ``` */ type ExtraOptions = { - raiseOnEmptyMetrics?: boolean + throwOnEmptyMetrics?: boolean defaultDimensions?: Dimensions captureColdStartMetric?: boolean }; diff --git a/packages/metrics/tests/e2e/decorator.test.MyFunction.ts b/packages/metrics/tests/e2e/decorator.test.MyFunction.ts index 3f3197401a..61f1720017 100644 --- a/packages/metrics/tests/e2e/decorator.test.MyFunction.ts +++ b/packages/metrics/tests/e2e/decorator.test.MyFunction.ts @@ -18,7 +18,7 @@ const metrics = new Metrics({ namespace: namespace, service: serviceName }); class Lambda implements LambdaInterface { - @metrics.logMetrics({ captureColdStartMetric: true, defaultDimensions: JSON.parse(defaultDimensions), raiseOnEmptyMetrics: true }) + @metrics.logMetrics({ captureColdStartMetric: true, defaultDimensions: JSON.parse(defaultDimensions), throwOnEmptyMetrics: true }) public async handler(_event: unknown, _context: Context): Promise { metrics.addMetric(metricName, metricUnit, parseInt(metricValue)); metrics.addDimension( diff --git a/packages/metrics/tests/e2e/standardFunctions.test.MyFunction.ts b/packages/metrics/tests/e2e/standardFunctions.test.MyFunction.ts index 6daa8d3ce4..732ab872b4 100644 --- a/packages/metrics/tests/e2e/standardFunctions.test.MyFunction.ts +++ b/packages/metrics/tests/e2e/standardFunctions.test.MyFunction.ts @@ -17,7 +17,7 @@ const metrics = new Metrics({ namespace: namespace, serviceName: serviceName }); export const handler = async (_event: unknown, _context: Context): Promise => { metrics.captureColdStartMetric(); - metrics.raiseOnEmptyMetrics(); + metrics.throwOnEmptyMetrics(); metrics.setDefaultDimensions(JSON.parse(defaultDimensions)); metrics.addMetric(metricName, metricUnit, parseInt(metricValue)); metrics.addDimension( diff --git a/packages/metrics/tests/unit/Metrics.test.ts b/packages/metrics/tests/unit/Metrics.test.ts index 216e702782..0e3dcf1a0e 100644 --- a/packages/metrics/tests/unit/Metrics.test.ts +++ b/packages/metrics/tests/unit/Metrics.test.ts @@ -346,13 +346,13 @@ describe('Class: Metrics', () => { }); }); - describe('Feature: raiseOnEmptyMetrics', () => { - test('Error should be thrown on empty metrics when raiseOnEmptyMetrics is passed', async () => { + describe('Feature: throwOnEmptyMetrics', () => { + test('Error should be thrown on empty metrics when throwOnEmptyMetrics is passed', async () => { expect.assertions(1); const metrics = new Metrics({ namespace: 'test' }); class LambdaFunction implements LambdaInterface { - @metrics.logMetrics({ raiseOnEmptyMetrics: true }) + @metrics.logMetrics({ throwOnEmptyMetrics: true }) // eslint-disable-next-line @typescript-eslint/ban-ts-comment // @ts-ignore public handler( @@ -371,12 +371,12 @@ describe('Class: Metrics', () => { } }); - test('Error should be thrown on empty metrics when raiseOnEmptyMetrics() is callse', async () => { + test('Error should be thrown on empty metrics when throwOnEmptyMetrics() is callse', async () => { expect.assertions(1); const metrics = new Metrics({ namespace: 'test' }); const handler = async (_event: DummyEvent, _context: Context): Promise => { - metrics.raiseOnEmptyMetrics(); + metrics.throwOnEmptyMetrics(); // Logic goes here metrics.publishStoredMetrics(); }; diff --git a/packages/metrics/tests/unit/middleware/middy.test.ts b/packages/metrics/tests/unit/middleware/middy.test.ts index 4bfd4655a6..bd9385dd23 100644 --- a/packages/metrics/tests/unit/middleware/middy.test.ts +++ b/packages/metrics/tests/unit/middleware/middy.test.ts @@ -86,7 +86,7 @@ describe('Middy middleware', () => { metrics.addMetric('successfulBooking', MetricUnits.Count, 1); }; const metricsOptions: ExtraOptions = { - raiseOnEmptyMetrics: true, + throwOnEmptyMetrics: true, defaultDimensions: { environment : 'prod', aws_region: 'eu-central-1' }, captureColdStartMetric: true }; @@ -173,7 +173,7 @@ describe('Middy middleware', () => { metrics.addMetric('successfulBooking', MetricUnits.Count, 1); }; const metricsOptions: ExtraOptions = { - raiseOnEmptyMetrics: true + throwOnEmptyMetrics: true }; const handler = middy(lambdaHandler).use(logMetrics([metrics], metricsOptions)); From 11d7e298aaec4d2ffb19840bd7adbd10df9a37e5 Mon Sep 17 00:00:00 2001 From: Grzegorz Kozub Date: Thu, 6 Jan 2022 12:54:02 +0100 Subject: [PATCH 2/3] refactor(metrics): update comments to follow new naming convention of throwOnEmptyMetrics property --- docs/core/metrics.md | 4 ++-- packages/metrics/examples/decorator/empty-metrics.ts | 2 +- packages/metrics/examples/empty-metrics.ts | 2 +- packages/metrics/src/Metrics.ts | 4 ++-- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/core/metrics.md b/docs/core/metrics.md index ac7ca3ee18..f574d720dd 100644 --- a/docs/core/metrics.md +++ b/docs/core/metrics.md @@ -274,12 +274,12 @@ You can flush metrics automatically using one of the following methods: * [Middy-compatible](https://github.com/middyjs/middy){target=_blank} middleware * class decorator -Using the Middy middleware or decorator will **automatically validate, serialize, and flush** all your metrics. During metrics validation, if no metrics are provided then a warning will be logged, but no exception will be raised. +Using the Middy middleware or decorator will **automatically validate, serialize, and flush** all your metrics. During metrics validation, if no metrics are provided then a warning will be logged, but no exception will be thrown. If you do not use the middleware or decorator, you have to flush your metrics manually. !!! warning "Metric validation" - If metrics are provided, and any of the following criteria are not met, a **`RangeError`** exception will be raised: + If metrics are provided, and any of the following criteria are not met, a **`RangeError`** exception will be thrown: * Maximum of 9 dimensions * Namespace is set only once (or none) diff --git a/packages/metrics/examples/decorator/empty-metrics.ts b/packages/metrics/examples/decorator/empty-metrics.ts index 008e5b6182..a3728fc638 100644 --- a/packages/metrics/examples/decorator/empty-metrics.ts +++ b/packages/metrics/examples/decorator/empty-metrics.ts @@ -19,7 +19,7 @@ class Lambda implements LambdaInterface { @metrics.logMetrics({ throwOnEmptyMetrics: true }) public handler(_event: TEvent, _context: Context, _callback: Callback): void | Promise { // Notice that no metrics are added - // Since the throwOnEmptyMetrics parameter is set to true, the Powertool throw an Error + // Since the throwOnEmptyMetrics parameter is set to true, the Powertool throws an Error } } diff --git a/packages/metrics/examples/empty-metrics.ts b/packages/metrics/examples/empty-metrics.ts index dedb0ccfc6..ed4e9d4633 100644 --- a/packages/metrics/examples/empty-metrics.ts +++ b/packages/metrics/examples/empty-metrics.ts @@ -14,7 +14,7 @@ const metrics = new Metrics(); const lambdaHandler = async (): Promise => { // Notice that no metrics are added - // Since the throwOnEmptyMetrics parameter is set to true, the Powertool throw an Error + // Since the throwOnEmptyMetrics parameter is set to true, the Powertool throws an Error }; const handlerWithMiddleware = middy(lambdaHandler) diff --git a/packages/metrics/src/Metrics.ts b/packages/metrics/src/Metrics.ts index 4b7a88e129..c6de6a8376 100644 --- a/packages/metrics/src/Metrics.ts +++ b/packages/metrics/src/Metrics.ts @@ -35,7 +35,7 @@ const DEFAULT_NAMESPACE = 'default_namespace'; * If you are used to TypeScript Class usage to encapsulate your Lambda handler you can leverage the [@metrics.logMetrics()](./_aws_lambda_powertools_metrics.Metrics.html#logMetrics) decorator to automatically: * * create cold start metric * * flush buffered metrics - * * raise on empty metrics + * * throw on empty metrics * * @example * @@ -202,7 +202,7 @@ class Metrics implements MetricsInterface { } /** - * A decorator automating coldstart capture, raise on empty metrics and publishing metrics on handler exit. + * A decorator automating coldstart capture, throw on empty metrics and publishing metrics on handler exit. * * @example * From bc77747fb98917fab5786aadce5e19ea1f46ea4d Mon Sep 17 00:00:00 2001 From: Grzegorz Kozub Date: Thu, 6 Jan 2022 18:08:49 +0100 Subject: [PATCH 3/3] refactor(metrics): update usage examples to follow new naming convention of throwOnEmptyMetrics property --- examples/cdk/lib/example-function.MyFunction.ts | 4 ++-- examples/cdk/lib/example-function.MyFunctionWithDecorator.ts | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/examples/cdk/lib/example-function.MyFunction.ts b/examples/cdk/lib/example-function.MyFunction.ts index 2e8e778427..a33268afa1 100644 --- a/examples/cdk/lib/example-function.MyFunction.ts +++ b/examples/cdk/lib/example-function.MyFunction.ts @@ -29,7 +29,7 @@ export const handler = async (_event: unknown, context: Context): Promise // ### Experiment metrics metrics.captureColdStartMetric(); - metrics.raiseOnEmptyMetrics(); + metrics.throwOnEmptyMetrics(); metrics.setDefaultDimensions({ environment: 'example', type: 'standardFunction' }); metrics.addMetric('test-metric', MetricUnits.Count, 10); @@ -38,7 +38,7 @@ export const handler = async (_event: unknown, context: Context): Promise metricWithItsOwnDimensions.addMetric('single-metric', MetricUnits.Percent, 50); metrics.purgeStoredMetrics(); - metrics.raiseOnEmptyMetrics(); + metrics.throwOnEmptyMetrics(); // ### Experiment tracer diff --git a/examples/cdk/lib/example-function.MyFunctionWithDecorator.ts b/examples/cdk/lib/example-function.MyFunctionWithDecorator.ts index 9715539f74..35cede722c 100644 --- a/examples/cdk/lib/example-function.MyFunctionWithDecorator.ts +++ b/examples/cdk/lib/example-function.MyFunctionWithDecorator.ts @@ -15,7 +15,7 @@ export class MyFunctionWithDecorator { @logger.injectLambdaContext() @metrics.logMetrics({ captureColdStartMetric: true, - raiseOnEmptyMetrics: true, + throwOnEmptyMetrics: true, defaultDimensions: { environment: 'example', type: 'withDecorator' }, }) public handler(_event: unknown, _context: Context, _callback: Callback): void | Promise {