Skip to content

Commit 242e80d

Browse files
sdangolsvozza
sdangol
and
svozza
authored
docs(metrics): Improved documentation for adding dimensions (#4763)
Co-authored-by: Stefano Vozza <[email protected]>
1 parent a470892 commit 242e80d

File tree

9 files changed

+204
-106
lines changed

9 files changed

+204
-106
lines changed

‎docs/features/metrics.md‎

Lines changed: 35 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -105,32 +105,57 @@ You can initialize Metrics anywhere in your code - It'll keep track of your aggr
105105

106106
### Creating metrics
107107

108-
You can create metrics using the `addMetric` method, and you can create dimensions for all your aggregate metrics using the `addDimension` method.
108+
You can create metrics using the `addMetric` method. Metrics are automatically associated with your configured namespace and dimensions.
109109

110110
=== "Metrics"
111111

112112
```typescript hl_lines="12"
113113
--8<-- "examples/snippets/metrics/createMetrics.ts"
114114
```
115115

116+
=== "Cloudwatch Log"
117+
118+
```json
119+
--8<-- "examples/snippets/metrics/samples/createMetricsLog.json"
120+
```
121+
122+
### Adding dimensions
123+
124+
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.
125+
126+
!!! note
127+
The `addDimension` method appends the dimension to the first `DimensionSet` in the `DimensionSet` array. To create a new `DimensionSet`, use the `addDimensions` method.
128+
116129
=== "Metrics with custom dimensions"
117130

118131
```typescript hl_lines="12-13"
119132
--8<-- "examples/snippets/metrics/customDimensions.ts"
120133
```
121134

122-
### Creating dimension sets
135+
=== "Cloudwatch Log"
123136

124-
You can create separate dimension sets for your metrics using the `addDimensions` method. This allows you to group metrics by different dimension combinations.
137+
```json
138+
--8<-- "examples/snippets/metrics/samples/customDimensionsLog.json"
139+
```
140+
141+
### Creating a `DimensionSet`
142+
143+
You can create a separate `DimensionSet` for your metrics using the `addDimensions` method. This allows you to group metrics by different dimension combinations.
125144

126-
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.
145+
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.
127146

128147
=== "handler.ts"
129148

130-
```typescript hl_lines="9 12-15 18-21"
149+
```typescript hl_lines="9 15-19 21-25"
131150
--8<-- "examples/snippets/metrics/dimensionSets.ts"
132151
```
133152

153+
=== "Cloudwatch Log"
154+
155+
```json
156+
--8<-- "examples/snippets/metrics/samples/dimensionSetsLog.json"
157+
```
158+
134159
!!! tip "Autocomplete Metric Units"
135160
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".
136161

@@ -168,32 +193,7 @@ You can call `addMetric()` with the same name multiple times. The values will be
168193
=== "Example CloudWatch Logs excerpt"
169194

170195
```json hl_lines="2-5 18-19"
171-
{
172-
"performedActionA": [
173-
2,
174-
1
175-
],
176-
"_aws": {
177-
"Timestamp": 1592234975665,
178-
"CloudWatchMetrics": [
179-
{
180-
"Namespace": "serverlessAirline",
181-
"Dimensions": [
182-
[
183-
"service"
184-
]
185-
],
186-
"Metrics": [
187-
{
188-
"Name": "performedActionA",
189-
"Unit": "Count"
190-
}
191-
]
192-
}
193-
]
194-
},
195-
"service": "orders"
196-
}
196+
--8<-- "examples/snippets/metrics/samples/multiValueMetricsLog.json"
197197
```
198198

199199
### Adding default dimensions
@@ -278,23 +278,7 @@ See below an example of how to automatically flush metrics with the Middy-compat
278278
=== "Example CloudWatch Logs excerpt"
279279

280280
```json
281-
{
282-
"successfulBooking": 1.0,
283-
"_aws": {
284-
"Timestamp": 1592234975665,
285-
"CloudWatchMetrics": [{
286-
"Namespace": "serverlessAirline",
287-
"Dimensions": [
288-
[ "service" ]
289-
],
290-
"Metrics": [{
291-
"Name": "successfulBooking",
292-
"Unit": "Count"
293-
}]
294-
}]
295-
},
296-
"service": "orders"
297-
}
281+
--8<-- "examples/snippets/metrics/samples/middyLog.json"
298282
```
299283

300284
#### Using the class decorator
@@ -319,23 +303,7 @@ The `logMetrics` decorator of the metrics utility can be used when your Lambda h
319303
=== "Example CloudWatch Logs excerpt"
320304

321305
```json
322-
{
323-
"successfulBooking": 1.0,
324-
"_aws": {
325-
"Timestamp": 1592234975665,
326-
"CloudWatchMetrics": [{
327-
"Namespace": "successfulBooking",
328-
"Dimensions": [
329-
[ "service" ]
330-
],
331-
"Metrics": [{
332-
"Name": "successfulBooking",
333-
"Unit": "Count"
334-
}]
335-
}]
336-
},
337-
"service": "orders"
338-
}
306+
--8<-- "examples/snippets/metrics/samples/decoratorLog.json"
339307
```
340308

341309
#### Manually
@@ -354,23 +322,7 @@ You can manually flush the metrics with `publishStoredMetrics` as follows:
354322
=== "Example CloudWatch Logs excerpt"
355323

356324
```json
357-
{
358-
"successfulBooking": 1.0,
359-
"_aws": {
360-
"Timestamp": 1592234975665,
361-
"CloudWatchMetrics": [{
362-
"Namespace": "successfulBooking",
363-
"Dimensions": [
364-
[ "service" ]
365-
],
366-
"Metrics": [{
367-
"Name": "successfulBooking",
368-
"Unit": "Count"
369-
}]
370-
}]
371-
},
372-
"service": "orders"
373-
}
325+
--8<-- "examples/snippets/metrics/samples/manualLog.json"
374326
```
375327

376328
#### 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
448400
=== "Example CloudWatch Logs excerpt"
449401

450402
```json hl_lines="31"
451-
{
452-
"successfulBooking": 1.0,
453-
"_aws": {
454-
"Timestamp": 1592234975665,
455-
"CloudWatchMetrics": [{
456-
"Namespace": "serverlessAirline",
457-
"Dimensions": [
458-
[ "service" ]
459-
],
460-
"Metrics": [{
461-
"Namespace": "exampleApplication",
462-
"Dimensions": [
463-
[ "service" ]
464-
],
465-
"Metrics": [{
466-
"Name": "successfulBooking",
467-
"Unit": "Count"
468-
}]
469-
}]
470-
}]
471-
},
472-
"service": "orders",
473-
"bookingId": "7051cd10-6283-11ec-90d6-0242ac120003"
474-
}
403+
--8<-- "examples/snippets/metrics/samples/addMetadataLog.json"
475404
```
476405

477406
### Single metric with different dimensions

‎examples/snippets/metrics/samples/addMetadataLog.json‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
{
2+
"successfulBooking": 1.0,
3+
"_aws": {
4+
"Timestamp": 1592234975665,
5+
"CloudWatchMetrics": [
6+
{
7+
"Namespace": "serverlessAirline",
8+
"Dimensions": [["service"]],
9+
"Metrics": [
10+
{
11+
"Namespace": "exampleApplication",
12+
"Dimensions": [["service"]],
13+
"Metrics": [
14+
{
15+
"Name": "successfulBooking",
16+
"Unit": "Count"
17+
}
18+
]
19+
}
20+
]
21+
}
22+
]
23+
},
24+
"service": "orders",
25+
"bookingId": "7051cd10-6283-11ec-90d6-0242ac120003"
26+
}

‎examples/snippets/metrics/samples/createMetricsLog.json‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{
2+
"_aws": {
3+
"Timestamp": 1763409658885,
4+
"CloudWatchMetrics": [
5+
{
6+
"Namespace": "serverlessAirline",
7+
"Dimensions": [["service"]],
8+
"Metrics": [
9+
{
10+
"Name": "successfulBooking",
11+
"Unit": "Count"
12+
}
13+
]
14+
}
15+
]
16+
},
17+
"service": "orders",
18+
"successfulBooking": 1
19+
}

‎examples/snippets/metrics/samples/customDimensionsLog.json‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"_aws": {
3+
"Timestamp": 1763409658885,
4+
"CloudWatchMetrics": [
5+
{
6+
"Namespace": "serverlessAirline",
7+
"Dimensions": [["service", "environment"]],
8+
"Metrics": [
9+
{
10+
"Name": "successfulBooking",
11+
"Unit": "Count"
12+
}
13+
]
14+
}
15+
]
16+
},
17+
"service": "orders",
18+
"environment": "prod",
19+
"successfulBooking": 1
20+
}

‎examples/snippets/metrics/samples/decoratorLog.json‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{
2+
"successfulBooking": 1.0,
3+
"_aws": {
4+
"Timestamp": 1592234975665,
5+
"CloudWatchMetrics": [
6+
{
7+
"Namespace": "successfulBooking",
8+
"Dimensions": [["service"]],
9+
"Metrics": [
10+
{
11+
"Name": "successfulBooking",
12+
"Unit": "Count"
13+
}
14+
]
15+
}
16+
]
17+
},
18+
"service": "orders"
19+
}

‎examples/snippets/metrics/samples/dimensionSetsLog.json‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
{
2+
"_aws": {
3+
"Timestamp": 1763409658885,
4+
"CloudWatchMetrics": [
5+
{
6+
"Namespace": "serverlessAirline",
7+
"Dimensions": [
8+
["service", "environment"],
9+
["dimension1", "dimension2"],
10+
["region", "category"]
11+
],
12+
"Metrics": [
13+
{
14+
"Name": "successfulBooking",
15+
"Unit": "Count"
16+
}
17+
]
18+
}
19+
]
20+
},
21+
"service": "orders",
22+
"environment": "prod",
23+
"dimension1": "1",
24+
"dimension2": "2",
25+
"region": "us-east-1",
26+
"category": "books",
27+
"successfulBooking": 1
28+
}

‎examples/snippets/metrics/samples/manualLog.json‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{
2+
"successfulBooking": 1.0,
3+
"_aws": {
4+
"Timestamp": 1592234975665,
5+
"CloudWatchMetrics": [
6+
{
7+
"Namespace": "successfulBooking",
8+
"Dimensions": [["service"]],
9+
"Metrics": [
10+
{
11+
"Name": "successfulBooking",
12+
"Unit": "Count"
13+
}
14+
]
15+
}
16+
]
17+
},
18+
"service": "orders"
19+
}

‎examples/snippets/metrics/samples/middyLog.json‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{
2+
"successfulBooking": 1.0,
3+
"_aws": {
4+
"Timestamp": 1592234975665,
5+
"CloudWatchMetrics": [
6+
{
7+
"Namespace": "serverlessAirline",
8+
"Dimensions": [["service"]],
9+
"Metrics": [
10+
{
11+
"Name": "successfulBooking",
12+
"Unit": "Count"
13+
}
14+
]
15+
}
16+
]
17+
},
18+
"service": "orders"
19+
}

‎examples/snippets/metrics/samples/multiValueMetricsLog.json‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{
2+
"performedActionA": [2, 1],
3+
"_aws": {
4+
"Timestamp": 1592234975665,
5+
"CloudWatchMetrics": [
6+
{
7+
"Namespace": "serverlessAirline",
8+
"Dimensions": [["service"]],
9+
"Metrics": [
10+
{
11+
"Name": "performedActionA",
12+
"Unit": "Count"
13+
}
14+
]
15+
}
16+
]
17+
},
18+
"service": "orders"
19+
}

0 commit comments

Comments
 (0)