diff --git a/docs/core/metrics.md b/docs/core/metrics.md index 2e9b63b3bc..d47a6416a5 100644 --- a/docs/core/metrics.md +++ b/docs/core/metrics.md @@ -398,7 +398,7 @@ This has the advantage of keeping cold start metric separate from your applicati 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. -!!! warning +!!! info **This will not be available during metrics visualization** - Use **dimensions** for this purpose === "handler.ts" @@ -440,24 +440,18 @@ You can add high-cardinality data as part of your Metrics log with the `addMetad CloudWatch EMF uses the same dimensions across all your metrics. Use `singleMetric` if you have a metric that should have different dimensions. -!!! info - For cost-efficiency, this feature would be used sparsely since you [pay for unique metric](https://aws.amazon.com/cloudwatch/pricing). Keep the following formula in mind: +Generally, using different dimensions would be an edge case since you [pay for unique metric](https://aws.amazon.com/cloudwatch/pricing). - **unique metric = (metric_name + dimension_name + dimension_value)** +Keep the following formula in mind: `unique metric = (metric_name + dimension_name + dimension_value)`. -=== "Middy Middleware" +=== "Single Metric" - ```typescript hl_lines="21 23-24" - --8<-- "examples/snippets/metrics/singleMetricDifferentDimsMiddy.ts" + ```typescript hl_lines="9" + --8<-- "examples/snippets/metrics/singleMetric.ts" ``` -=== "logMetrics decorator" - - ```typescript hl_lines="16 18-19" - --8<-- "examples/snippets/metrics/singleMetricDifferentDimsDecorator.ts" - ``` - - 1. Binding your handler method allows your handler to access `this` within the class methods. + 1. Metadata should be added before calling `addMetric()` to ensure it's included in the same EMF blob. + 2. Single metrics are emitted as soon as `addMetric()` is called, so you don't need to call `publishStoredMetrics()`. ## Testing your code diff --git a/examples/snippets/metrics/singleMetric.ts b/examples/snippets/metrics/singleMetric.ts new file mode 100644 index 0000000000..d2889f48ce --- /dev/null +++ b/examples/snippets/metrics/singleMetric.ts @@ -0,0 +1,13 @@ +import { MetricUnit, Metrics } from '@aws-lambda-powertools/metrics'; + +const metrics = new Metrics({ + namespace: 'serverlessAirline', + serviceName: 'orders', +}); + +export const handler = async (event: { orderId: string }) => { + const singleMetric = metrics.singleMetric(); + singleMetric.addDimension('metricType', 'business'); + singleMetric.addMetadata('orderId', event.orderId); // (1)! + singleMetric.addMetric('successfulBooking', MetricUnit.Count, 1); // (2)! +}; diff --git a/examples/snippets/metrics/singleMetricDifferentDimsDecorator.ts b/examples/snippets/metrics/singleMetricDifferentDimsDecorator.ts deleted file mode 100644 index 4cdbde17b6..0000000000 --- a/examples/snippets/metrics/singleMetricDifferentDimsDecorator.ts +++ /dev/null @@ -1,24 +0,0 @@ -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', -}); - -class Lambda implements LambdaInterface { - @metrics.logMetrics() - public async handler(_event: unknown, _context: unknown): Promise { - metrics.addDimension('metricUnit', 'milliseconds'); - // This metric will have the "metricUnit" dimension, and no "metricType" dimension: - metrics.addMetric('latency', MetricUnit.Milliseconds, 56); - - const singleMetric = metrics.singleMetric(); - // This metric will have the "metricType" dimension, and no "metricUnit" dimension: - singleMetric.addDimension('metricType', 'business'); - singleMetric.addMetric('orderSubmitted', MetricUnit.Count, 1); - } -} - -const handlerClass = new Lambda(); -export const handler = handlerClass.handler.bind(handlerClass); // (1) diff --git a/examples/snippets/metrics/singleMetricDifferentDimsMiddy.ts b/examples/snippets/metrics/singleMetricDifferentDimsMiddy.ts deleted file mode 100644 index 31c3b70794..0000000000 --- a/examples/snippets/metrics/singleMetricDifferentDimsMiddy.ts +++ /dev/null @@ -1,24 +0,0 @@ -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 => { - metrics.addDimension('metricUnit', 'milliseconds'); - // This metric will have the "metricUnit" dimension, and no "metricType" dimension: - metrics.addMetric('latency', MetricUnit.Milliseconds, 56); - - const singleMetric = metrics.singleMetric(); - // This metric will have the "metricType" dimension, and no "metricUnit" dimension: - singleMetric.addDimension('metricType', 'business'); - singleMetric.addMetric('orderSubmitted', MetricUnit.Count, 1); -}; - -export const handler = middy(lambdaHandler).use(logMetrics(metrics)); diff --git a/packages/metrics/src/Metrics.ts b/packages/metrics/src/Metrics.ts index d34419dc28..559ff71b91 100644 --- a/packages/metrics/src/Metrics.ts +++ b/packages/metrics/src/Metrics.ts @@ -718,7 +718,7 @@ class Metrics extends Utility implements MetricsInterface { * export const handler = async () => { * const singleMetric = metrics.singleMetric(); * // The single metric will be emitted immediately - * singleMetric.addMetric('coldStart', MetricUnit.Count, 1); + * singleMetric.addMetric('ColdStart', MetricUnit.Count, 1); * * // These other metrics will be buffered and emitted when calling `publishStoredMetrics()` * metrics.addMetric('successfulBooking', MetricUnit.Count, 1);