Skip to content

Commit 514a9b8

Browse files
jeromevdljeromevdl
committed
update documentation
1 parent fd01069 commit 514a9b8

File tree

1 file changed

+37
-75
lines changed

1 file changed

+37
-75
lines changed

‎docs/core/metrics.md

Lines changed: 37 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,7 @@ If you're new to Amazon CloudWatch, there are two terminologies you must be awar
2828

2929
## Install
3030

31-
Depending on your version of Java (either Java 1.8 or 11+), the configuration slightly changes.
32-
33-
=== "Maven Java 11+"
31+
=== "Maven"
3432

3533
```xml hl_lines="3-7 16 18 24-27"
3634
<dependencies>
@@ -75,52 +73,7 @@ If you're new to Amazon CloudWatch, there are two terminologies you must be awar
7573
</build>
7674
```
7775

78-
=== "Maven Java 1.8"
79-
80-
```xml hl_lines="3-7 16 18 24-27"
81-
<dependencies>
82-
...
83-
<dependency>
84-
<groupId>software.amazon.lambda</groupId>
85-
<artifactId>powertools-metrics</artifactId>
86-
<version>{{ powertools.version }}</version>
87-
</dependency>
88-
...
89-
</dependencies>
90-
...
91-
<!-- configure the aspectj-maven-plugin to compile-time weave (CTW) the aws-lambda-powertools-java aspects into your project -->
92-
<build>
93-
<plugins>
94-
...
95-
<plugin>
96-
<groupId>org.codehaus.mojo</groupId>
97-
<artifactId>aspectj-maven-plugin</artifactId>
98-
<version>1.14.0</version>
99-
<configuration>
100-
<source>1.8</source>
101-
<target>1.8</target>
102-
<complianceLevel>1.8</complianceLevel>
103-
<aspectLibraries>
104-
<aspectLibrary>
105-
<groupId>software.amazon.lambda</groupId>
106-
<artifactId>powertools-metrics</artifactId>
107-
</aspectLibrary>
108-
</aspectLibraries>
109-
</configuration>
110-
<executions>
111-
<execution>
112-
<goals>
113-
<goal>compile</goal>
114-
</goals>
115-
</execution>
116-
</executions>
117-
</plugin>
118-
...
119-
</plugins>
120-
</build>
121-
```
122-
123-
=== "Gradle Java 11+"
76+
=== "Gradle"
12477

12578
```groovy hl_lines="3 11"
12679
plugins {
@@ -140,34 +93,14 @@ If you're new to Amazon CloudWatch, there are two terminologies you must be awar
14093
targetCompatibility = 11
14194
```
14295

143-
=== "Gradle Java 1.8"
144-
145-
```groovy hl_lines="3 11"
146-
plugins {
147-
id 'java'
148-
id 'io.freefair.aspectj.post-compile-weaving' version '6.6.3'
149-
}
150-
151-
repositories {
152-
mavenCentral()
153-
}
154-
155-
dependencies {
156-
aspect 'software.amazon.lambda:powertools-metrics:{{ powertools.version }}'
157-
}
158-
159-
sourceCompatibility = 1.8
160-
targetCompatibility = 1.8
161-
```
162-
16396
## Getting started
16497

16598
Metric has two global settings that will be used across all metrics emitted:
16699

167-
Setting | Description | Environment variable | Constructor parameter
168-
------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------
169-
**Metric namespace** | Logical container where all metrics will be placed e.g. `ServerlessAirline` | `POWERTOOLS_METRICS_NAMESPACE` | `namespace`
170-
**Service** | Optionally, sets **service** metric dimension across all metrics e.g. `payment` | `POWERTOOLS_SERVICE_NAME` | `service`
100+
| Setting | Description | Environment variable | Constructor parameter |
101+
|----------------------|---------------------------------------------------------------------------------|--------------------------------|-----------------------|
102+
| **Metric namespace** | Logical container where all metrics will be placed e.g. `ServerlessAirline` | `POWERTOOLS_METRICS_NAMESPACE` | `namespace` |
103+
| **Service** | Optionally, sets **service** metric dimension across all metrics e.g. `payment` | `POWERTOOLS_SERVICE_NAME` | `service` |
171104

172105
!!! tip "Use your application or main service as the metric namespace to easily group all metrics"
173106

@@ -198,7 +131,7 @@ Setting | Description | Environment variable | Constructor parameter
198131
@Override
199132
@Metrics(namespace = "ExampleApplication", service = "booking")
200133
public Object handleRequest(Object input, Context context) {
201-
...
134+
// ...
202135
}
203136
}
204137
```
@@ -224,7 +157,7 @@ You can create metrics using `putMetric`, and manually create dimensions for all
224157
public Object handleRequest(Object input, Context context) {
225158
metricsLogger.putDimensions(DimensionSet.of("environment", "prod"));
226159
metricsLogger.putMetric("SuccessfulBooking", 1, Unit.COUNT);
227-
...
160+
// ...
228161
}
229162
}
230163
```
@@ -234,6 +167,35 @@ You can create metrics using `putMetric`, and manually create dimensions for all
234167
!!! note "Metrics overflow"
235168
CloudWatch EMF supports a max of 100 metrics. Metrics utility will flush all metrics when adding the 100th metric while subsequent metrics will be aggregated into a new EMF object, for your convenience.
236169

170+
171+
### Adding high-resolution metrics
172+
173+
You can create [high-resolution metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/publishingMetrics.html#high-resolution-metrics)
174+
passing a `storageResolution` to the `putMetric` method:
175+
176+
=== "HigResMetricsHandler.java"
177+
178+
```java hl_lines="3 13"
179+
import software.amazon.lambda.powertools.metrics.Metrics;
180+
import software.amazon.cloudwatchlogs.emf.logger.MetricsLogger;
181+
import software.amazon.cloudwatchlogs.emf.model.StorageResolution;
182+
183+
public class MetricsEnabledHandler implements RequestHandler<Object, Object> {
184+
185+
MetricsLogger metricsLogger = MetricsUtils.metricsLogger();
186+
187+
@Override
188+
@Metrics(namespace = "ExampleApplication", service = "booking")
189+
public Object handleRequest(Object input, Context context) {
190+
// ...
191+
metricsLogger.putMetric("SuccessfulBooking", 1, Unit.COUNT, StorageResolution.HIGH);
192+
}
193+
}
194+
```
195+
196+
!!! info "When is it useful?"
197+
High-resolution metrics are data with a granularity of one second and are very useful in several situations such as telemetry, time series, real-time incident management, and others.
198+
237199
### Flushing metrics
238200

239201
The `@Metrics` annotation **validates**, **serializes**, and **flushes** all your metrics. During metrics validation,

0 commit comments

Comments
 (0)