diff --git a/docs/features/metrics.md b/docs/features/metrics.md index 615a3c6efb..6f1392e8d1 100644 --- a/docs/features/metrics.md +++ b/docs/features/metrics.md @@ -105,7 +105,7 @@ You can initialize Metrics anywhere in your code - It'll keep track of your aggr ### Creating metrics -You can create metrics using the `addMetric` method, and you can create dimensions for all your aggregate metrics using the `addDimension` method. +You can create metrics using the `addMetric` method. Metrics are automatically associated with your configured namespace and dimensions. === "Metrics" @@ -113,24 +113,49 @@ You can create metrics using the `addMetric` method, and you can create dimensio --8<-- "examples/snippets/metrics/createMetrics.ts" ``` +=== "Cloudwatch Log" + + ```json + --8<-- "examples/snippets/metrics/samples/createMetricsLog.json" + ``` + +### Adding dimensions + +By default, Powertools adds a `service` dimension in a [DimensionSet](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Specification.html){target="_blank"}. You can append additional dimensions for all your aggregate metrics using the `addDimension` method. + +!!! note + The `addDimension` method appends the dimension to the first `DimensionSet` in the `DimensionSet` array. To create a new `DimensionSet`, use the `addDimensions` method. + === "Metrics with custom dimensions" ```typescript hl_lines="12-13" --8<-- "examples/snippets/metrics/customDimensions.ts" ``` -### Creating dimension sets +=== "Cloudwatch Log" -You can create separate dimension sets for your metrics using the `addDimensions` method. This allows you to group metrics by different dimension combinations. + ```json + --8<-- "examples/snippets/metrics/samples/customDimensionsLog.json" + ``` + +### Creating a `DimensionSet` + +You can create a separate `DimensionSet` for your metrics using the `addDimensions` method. This allows you to group metrics by different dimension combinations. -When you call `addDimensions()`, it creates a new dimension set rather than adding to the existing dimensions. This is useful when you want to track the same metric across different dimension combinations. +When you call `addDimensions()`, it creates a new `DimensionSet` rather than adding to the first set. This is useful when you want to track the same metric across different dimension combinations. === "handler.ts" - ```typescript hl_lines="9 12-15 18-21" + ```typescript hl_lines="9 15-19 21-25" --8<-- "examples/snippets/metrics/dimensionSets.ts" ``` +=== "Cloudwatch Log" + + ```json + --8<-- "examples/snippets/metrics/samples/dimensionSetsLog.json" + ``` + !!! tip "Autocomplete Metric Units" Use the `MetricUnit` enum to easily find a supported metric unit by CloudWatch. Alternatively, you can pass the value as a string if you already know them e.g. "Count". @@ -168,32 +193,7 @@ You can call `addMetric()` with the same name multiple times. The values will be === "Example CloudWatch Logs excerpt" ```json hl_lines="2-5 18-19" - { - "performedActionA": [ - 2, - 1 - ], - "_aws": { - "Timestamp": 1592234975665, - "CloudWatchMetrics": [ - { - "Namespace": "serverlessAirline", - "Dimensions": [ - [ - "service" - ] - ], - "Metrics": [ - { - "Name": "performedActionA", - "Unit": "Count" - } - ] - } - ] - }, - "service": "orders" - } + --8<-- "examples/snippets/metrics/samples/multiValueMetricsLog.json" ``` ### Adding default dimensions @@ -278,23 +278,7 @@ See below an example of how to automatically flush metrics with the Middy-compat === "Example CloudWatch Logs excerpt" ```json - { - "successfulBooking": 1.0, - "_aws": { - "Timestamp": 1592234975665, - "CloudWatchMetrics": [{ - "Namespace": "serverlessAirline", - "Dimensions": [ - [ "service" ] - ], - "Metrics": [{ - "Name": "successfulBooking", - "Unit": "Count" - }] - }] - }, - "service": "orders" - } + --8<-- "examples/snippets/metrics/samples/middyLog.json" ``` #### Using the class decorator @@ -319,23 +303,7 @@ The `logMetrics` decorator of the metrics utility can be used when your Lambda h === "Example CloudWatch Logs excerpt" ```json - { - "successfulBooking": 1.0, - "_aws": { - "Timestamp": 1592234975665, - "CloudWatchMetrics": [{ - "Namespace": "successfulBooking", - "Dimensions": [ - [ "service" ] - ], - "Metrics": [{ - "Name": "successfulBooking", - "Unit": "Count" - }] - }] - }, - "service": "orders" - } + --8<-- "examples/snippets/metrics/samples/decoratorLog.json" ``` #### Manually @@ -354,23 +322,7 @@ You can manually flush the metrics with `publishStoredMetrics` as follows: === "Example CloudWatch Logs excerpt" ```json - { - "successfulBooking": 1.0, - "_aws": { - "Timestamp": 1592234975665, - "CloudWatchMetrics": [{ - "Namespace": "successfulBooking", - "Dimensions": [ - [ "service" ] - ], - "Metrics": [{ - "Name": "successfulBooking", - "Unit": "Count" - }] - }] - }, - "service": "orders" - } + --8<-- "examples/snippets/metrics/samples/manualLog.json" ``` #### Throwing a RangeError when no metrics are emitted @@ -448,30 +400,7 @@ You can add high-cardinality data as part of your Metrics log with the `addMetad === "Example CloudWatch Logs excerpt" ```json hl_lines="31" - { - "successfulBooking": 1.0, - "_aws": { - "Timestamp": 1592234975665, - "CloudWatchMetrics": [{ - "Namespace": "serverlessAirline", - "Dimensions": [ - [ "service" ] - ], - "Metrics": [{ - "Namespace": "exampleApplication", - "Dimensions": [ - [ "service" ] - ], - "Metrics": [{ - "Name": "successfulBooking", - "Unit": "Count" - }] - }] - }] - }, - "service": "orders", - "bookingId": "7051cd10-6283-11ec-90d6-0242ac120003" - } + --8<-- "examples/snippets/metrics/samples/addMetadataLog.json" ``` ### Single metric with different dimensions diff --git a/examples/snippets/metrics/samples/addMetadataLog.json b/examples/snippets/metrics/samples/addMetadataLog.json new file mode 100644 index 0000000000..d53fa7ecf6 --- /dev/null +++ b/examples/snippets/metrics/samples/addMetadataLog.json @@ -0,0 +1,26 @@ +{ + "successfulBooking": 1.0, + "_aws": { + "Timestamp": 1592234975665, + "CloudWatchMetrics": [ + { + "Namespace": "serverlessAirline", + "Dimensions": [["service"]], + "Metrics": [ + { + "Namespace": "exampleApplication", + "Dimensions": [["service"]], + "Metrics": [ + { + "Name": "successfulBooking", + "Unit": "Count" + } + ] + } + ] + } + ] + }, + "service": "orders", + "bookingId": "7051cd10-6283-11ec-90d6-0242ac120003" +} diff --git a/examples/snippets/metrics/samples/createMetricsLog.json b/examples/snippets/metrics/samples/createMetricsLog.json new file mode 100644 index 0000000000..7ed9f3f721 --- /dev/null +++ b/examples/snippets/metrics/samples/createMetricsLog.json @@ -0,0 +1,19 @@ +{ + "_aws": { + "Timestamp": 1763409658885, + "CloudWatchMetrics": [ + { + "Namespace": "serverlessAirline", + "Dimensions": [["service"]], + "Metrics": [ + { + "Name": "successfulBooking", + "Unit": "Count" + } + ] + } + ] + }, + "service": "orders", + "successfulBooking": 1 +} diff --git a/examples/snippets/metrics/samples/customDimensionsLog.json b/examples/snippets/metrics/samples/customDimensionsLog.json new file mode 100644 index 0000000000..01913cca12 --- /dev/null +++ b/examples/snippets/metrics/samples/customDimensionsLog.json @@ -0,0 +1,20 @@ +{ + "_aws": { + "Timestamp": 1763409658885, + "CloudWatchMetrics": [ + { + "Namespace": "serverlessAirline", + "Dimensions": [["service", "environment"]], + "Metrics": [ + { + "Name": "successfulBooking", + "Unit": "Count" + } + ] + } + ] + }, + "service": "orders", + "environment": "prod", + "successfulBooking": 1 +} diff --git a/examples/snippets/metrics/samples/decoratorLog.json b/examples/snippets/metrics/samples/decoratorLog.json new file mode 100644 index 0000000000..ef2d4d1021 --- /dev/null +++ b/examples/snippets/metrics/samples/decoratorLog.json @@ -0,0 +1,19 @@ +{ + "successfulBooking": 1.0, + "_aws": { + "Timestamp": 1592234975665, + "CloudWatchMetrics": [ + { + "Namespace": "successfulBooking", + "Dimensions": [["service"]], + "Metrics": [ + { + "Name": "successfulBooking", + "Unit": "Count" + } + ] + } + ] + }, + "service": "orders" +} diff --git a/examples/snippets/metrics/samples/dimensionSetsLog.json b/examples/snippets/metrics/samples/dimensionSetsLog.json new file mode 100644 index 0000000000..c2245c2c37 --- /dev/null +++ b/examples/snippets/metrics/samples/dimensionSetsLog.json @@ -0,0 +1,28 @@ +{ + "_aws": { + "Timestamp": 1763409658885, + "CloudWatchMetrics": [ + { + "Namespace": "serverlessAirline", + "Dimensions": [ + ["service", "environment"], + ["dimension1", "dimension2"], + ["region", "category"] + ], + "Metrics": [ + { + "Name": "successfulBooking", + "Unit": "Count" + } + ] + } + ] + }, + "service": "orders", + "environment": "prod", + "dimension1": "1", + "dimension2": "2", + "region": "us-east-1", + "category": "books", + "successfulBooking": 1 +} diff --git a/examples/snippets/metrics/samples/manualLog.json b/examples/snippets/metrics/samples/manualLog.json new file mode 100644 index 0000000000..ef2d4d1021 --- /dev/null +++ b/examples/snippets/metrics/samples/manualLog.json @@ -0,0 +1,19 @@ +{ + "successfulBooking": 1.0, + "_aws": { + "Timestamp": 1592234975665, + "CloudWatchMetrics": [ + { + "Namespace": "successfulBooking", + "Dimensions": [["service"]], + "Metrics": [ + { + "Name": "successfulBooking", + "Unit": "Count" + } + ] + } + ] + }, + "service": "orders" +} diff --git a/examples/snippets/metrics/samples/middyLog.json b/examples/snippets/metrics/samples/middyLog.json new file mode 100644 index 0000000000..bd41a11eb6 --- /dev/null +++ b/examples/snippets/metrics/samples/middyLog.json @@ -0,0 +1,19 @@ +{ + "successfulBooking": 1.0, + "_aws": { + "Timestamp": 1592234975665, + "CloudWatchMetrics": [ + { + "Namespace": "serverlessAirline", + "Dimensions": [["service"]], + "Metrics": [ + { + "Name": "successfulBooking", + "Unit": "Count" + } + ] + } + ] + }, + "service": "orders" +} diff --git a/examples/snippets/metrics/samples/multiValueMetricsLog.json b/examples/snippets/metrics/samples/multiValueMetricsLog.json new file mode 100644 index 0000000000..a3448ca221 --- /dev/null +++ b/examples/snippets/metrics/samples/multiValueMetricsLog.json @@ -0,0 +1,19 @@ +{ + "performedActionA": [2, 1], + "_aws": { + "Timestamp": 1592234975665, + "CloudWatchMetrics": [ + { + "Namespace": "serverlessAirline", + "Dimensions": [["service"]], + "Metrics": [ + { + "Name": "performedActionA", + "Unit": "Count" + } + ] + } + ] + }, + "service": "orders" +}