feat(metrics): refactoring cost improvement website docs and code comments

Author: niko-achilles

docs/core/metrics.md

@@ -27,6 +27,9 @@ If you're new to Amazon CloudWatch, there are two terminologies you must be awar
 
 * **Namespace**. It's the highest level container that will group multiple metrics from multiple services for a given application, for example `ServerlessEcommerce`.
 * **Dimensions**. Metrics metadata in key-value format. They help you slice and dice metrics visualization, for example `ColdStart` metric by Payment `service`.
+* **Metric**. It's the name of the metric, for example: SuccessfulBooking or UpdatedBooking.
+* **Unit**. It's a value representing the unit of measure for the corresponding metric, for example: Count or Seconds.
+* **Resolution**. It's a value representing the storage resolution for the corresponding metric. Metrics can be either Standard or High resolution. Read more [here](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Resolution_definition).
 
 <figure>
   <img src="../../media/metrics_terminology.png" />
@@ -117,7 +120,23 @@ You can create metrics using the `addMetric` method, and you can create dimensio
     CloudWatch EMF supports a max of 100 metrics per batch. Metrics will automatically propagate all the metrics when adding the 100th metric. Subsequent metrics, e.g. 101th, will be aggregated into a new EMF object, for your convenience.
 
 !!! warning "Do not create metrics or dimensions outside the handler"
-    Metrics or dimensions added in the global scope will only be added during cold start. Disregard if that's the intended behaviour.
+    Metrics or dimensions added in the global scope will only be added during cold start. Disregard if that's the intended behavior.
+
+### Adding high-resolution metrics
+
+You can create [high-resolution metrics](https://aws.amazon.com/about-aws/whats-new/2023/02/amazon-cloudwatch-high-resolution-metric-extraction-structured-logs/) passing `resolution` as parameter to `addMetric`. 
+
+!!! tip "When is it useful?"
+    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.
+
+=== "Metrics with high resolution"
+
+    ```typescript hl_lines="6"
+    --8<-- "docs/snippets/metrics/addHighResolutionMetric.ts"
+    ```
+
+!!! tip "Autocomplete Metric Resolutions"
+    Use the `MetricResolution` type to easily find a supported metric resolution by CloudWatch. Alternatively, you can pass the allowed values of 1 or 60 as an integer.
 
 ### Adding multi-value metrics
 

docs/snippets/metrics/addHighResolutionMetric.ts

@@ -0,0 +1,7 @@
+import { Metrics, MetricUnits, MetricResolution } from '@aws-lambda-powertools/metrics';
+
+const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });
+
+export const handler = async (_event: unknown, _context: unknown): Promise<void> => {
+  metrics.addMetric('successfulBooking', MetricUnits.Count, 1, MetricResolution.High);
+};

docs/snippets/metrics/basicUsage.ts

@@ -2,6 +2,6 @@ import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
 
 const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });
 
-export const handler = async (_event, _context): Promise<void> => {
+export const handler = async (_event: unknown, _context: unknown): Promise<void> => {
   metrics.addMetric('successfulBooking', MetricUnits.Count, 1);
 };

docs/snippets/metrics/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "noEmit": true,
+    "strict": true,
+    "noImplicitAny": true,
+    "experimentalDecorators": true,
+    "moduleResolution": "node",
+    "skipLibCheck": true,
+    "pretty": true,
+    "resolveJsonModule": true,
+    "baseUrl": ".",
+    "paths": {
+      "@aws-lambda-powertools/metrics": ["../../../packages/metrics/src"]
+    }
+  },
+  "exclude": ["./node_modules"],
+  "lib": ["ES2020"],
+  "types": ["node"]
+}

packages/metrics/src/Metrics.ts

@@ -12,6 +12,8 @@ import {
   MetricUnit,
   MetricUnits,
   MetricResolution,
+  MetricDefinition,
+  StoredMetric,
 } from './types';
 
 const MAX_METRICS_SIZE = 100;
@@ -166,13 +168,32 @@ class Metrics extends Utility implements MetricsInterface {
 
   /**
    * Add a metric to the metrics buffer.
-   * @param name
-   * @param unit
-   * @param value
-   * @param resolution
+   *
+   * @example 
+   *
+   * Add Metric using MetricUnit Enum supported by Cloudwatch
+   * 
+   * ```ts
+   * metrics.addMetric('successfulBooking', MetricUnits.Count, 1);
+   * ```
+   * 
+   * @example 
+   * 
+   * Add Metric using MetricResolution type with resolutions High or Standard supported by cloudwatch 
+   * 
+   * ```ts
+   * metrics.addMetric('successfulBooking', MetricUnits.Count, 1, MetricResolution.High);
+   * ```
+   * 
+   * @param name - The metric name 
+   * @param unit - The metric unit
+   * @param value - The metric value
+   * @param resolution - The metric resolution
+   * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Resolution_definition Amazon Cloudwatch Concepts Documentation  
+   * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Specification.html#CloudWatch_Embedded_Metric_Format_Specification_structure_metricdefinition Metric Definition of Embedded Metric Format Specification
    */
 
-  public addMetric(name: string, unit: MetricUnit, value: number, resolution?: MetricResolution): void {
+  public addMetric(name: string, unit: MetricUnit, value: number, resolution: MetricResolution = MetricResolution.Standard): void {
     this.storeMetric(name, unit, value, resolution);
     if (this.isSingleMetric) this.publishStoredMetrics();
   }
@@ -317,19 +338,28 @@ class Metrics extends Utility implements MetricsInterface {
   }
 
   /**
-   * Function to create the right object compliant with Cloudwatch EMF (Event Metric Format).
+   * Function to create the right object compliant with Cloudwatch EMF (Embedded Metric Format).
+   * 
+   * 
+   * @returns metrics as JSON object compliant EMF Schema Specification
    * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Specification.html for more details
-   * @returns {string}
    */
   public serializeMetrics(): EmfOutput {
-    const metricDefinitions = Object.values(this.storedMetrics).map((metricDefinition) => metricDefinition.resolution ? ({
-      Name: metricDefinition.name,
-      Unit: metricDefinition.unit,
-      StorageResolution: metricDefinition.resolution
-    }): ({
-      Name: metricDefinition.name,
-      Unit: metricDefinition.unit
-    }));
+    // For high-resolution metrics, add StorageResolution property
+    // Example: [ { "Name": "metric_name", "Unit": "Count", "StorageResolution": 1 } ]
+
+    // For standard resolution metrics, don't add StorageResolution property to avoid unnecessary ingestion of data into cloudwatch
+    // Example: [ { "Name": "metric_name", "Unit": "Count"} ]
+    const metricDefinitions: MetricDefinition[] = Object.values(this.storedMetrics).map((metricDefinition) => 
+      this.isHigh(metricDefinition['resolution']) 
+        ? ({
+          Name: metricDefinition.name,
+          Unit: metricDefinition.unit,
+          StorageResolution: metricDefinition.resolution
+        }): ({
+          Name: metricDefinition.name,
+          Unit: metricDefinition.unit,
+        }));
 
     if (metricDefinitions.length === 0 && this.shouldThrowOnEmptyMetrics) {
       throw new RangeError('The number of metrics recorded must be higher than zero');
@@ -437,6 +467,10 @@ class Metrics extends Utility implements MetricsInterface {
     return <EnvironmentVariablesService> this.envVarsService;
   }
 
+  private isHigh(resolution: StoredMetric['resolution']): resolution is 1 {
+    return resolution === MetricResolution.High;
+  }
+
   private isNewMetric(name: string, unit: MetricUnit): boolean {
     if (this.storedMetrics[name]){
       // Inconsistent units indicates a bug or typos and we want to flag this to users early
@@ -491,7 +525,7 @@ class Metrics extends Utility implements MetricsInterface {
     name: string,
     unit: MetricUnit,
     value: number,
-    resolution?: MetricResolution,
+    resolution: MetricResolution,
   ): void {    
     if (Object.keys(this.storedMetrics).length >= MAX_METRICS_SIZE) {
       this.publishStoredMetrics();
@@ -501,10 +535,10 @@ class Metrics extends Utility implements MetricsInterface {
       this.storedMetrics[name] = {
         unit,
         value,
-        name,
-        resolution,      
+        name, 
+        resolution    
       };
-      
+       
     } else {
       const storedMetric = this.storedMetrics[name];
       if (!Array.isArray(storedMetric.value)) {

packages/metrics/src/types/Metrics.ts

@@ -21,11 +21,7 @@ type EmfOutput = {
     CloudWatchMetrics: {
       Namespace: string
       Dimensions: [string[]]   
-      Metrics: {
-        Name: string
-        Unit: MetricUnit
-        StorageResolution?: MetricResolution
-      }[]    
+      Metrics: MetricDefinition[]    
     }[]
   }
 };
@@ -65,11 +61,17 @@ type StoredMetric = {
   name: string
   unit: MetricUnit
   value: number | number[]
-  resolution?: MetricResolution
+  resolution: MetricResolution
 };
 
 type StoredMetrics = {
   [key: string]: StoredMetric
 };
 
-export { MetricsOptions, Dimensions, EmfOutput, HandlerMethodDecorator, ExtraOptions, StoredMetrics };
+type MetricDefinition = {
+  Name: string
+  Unit: MetricUnit
+  StorageResolution?: MetricResolution
+}; 
+
+export { MetricsOptions, Dimensions, EmfOutput, HandlerMethodDecorator, ExtraOptions, StoredMetrics, StoredMetric, MetricDefinition };

packages/metrics/tests/unit/Metrics.test.ts

@@ -576,25 +576,30 @@ describe('Class: Metrics', () => {
       expect(Object.keys(serializedMetrics._aws.CloudWatchMetrics[0].Metrics[0])).toContain('Unit');
 
     });
-    test('should set StorageResolution 60 if MetricResolution is set to `Standard`', () => {
+    test('serialized metrics in EMF format should not contain `StorageResolution` as key if `Standard` is set', () => {
       const metrics = new Metrics();
       metrics.addMetric('test_name', MetricUnits.Seconds, 10, MetricResolution.Standard);
       const serializedMetrics = metrics.serializeMetrics();
 
-      expect(serializedMetrics._aws.CloudWatchMetrics[0].Metrics[0].StorageResolution).toBe(MetricResolution.Standard);
-      expect(serializedMetrics._aws.CloudWatchMetrics[0].Metrics[0].StorageResolution).toBe(60);
+      // expect(serializedMetrics._aws.CloudWatchMetrics[0].Metrics[0].StorageResolution).toBe(MetricResolution.Standard);
+      // expect(serializedMetrics._aws.CloudWatchMetrics[0].Metrics[0].StorageResolution).toBe(60);
+
+      expect(Object.keys(serializedMetrics._aws.CloudWatchMetrics[0].Metrics[0])).not.toContain('StorageResolution');
+      expect(Object.keys(serializedMetrics._aws.CloudWatchMetrics[0].Metrics[0])).toContain('Name');
+      expect(Object.keys(serializedMetrics._aws.CloudWatchMetrics[0].Metrics[0])).toContain('Unit');
     });
 
-    test('Should be StorageResolution 60 if MetricResolution is set to `60`',()=>{
+    test('serialized metrics in EMF format should not contain `StorageResolution` as key if `60` is set',()=>{
       const metrics = new Metrics();
       metrics.addMetric('test_name', MetricUnits.Seconds, 10, 60);
       const serializedMetrics = metrics.serializeMetrics();
 
-      expect(serializedMetrics._aws.CloudWatchMetrics[0].Metrics[0].StorageResolution).toBe(MetricResolution.Standard);
-      expect(serializedMetrics._aws.CloudWatchMetrics[0].Metrics[0].StorageResolution).toBe(60);
+      expect(Object.keys(serializedMetrics._aws.CloudWatchMetrics[0].Metrics[0])).not.toContain('StorageResolution');
+      expect(Object.keys(serializedMetrics._aws.CloudWatchMetrics[0].Metrics[0])).toContain('Name');
+      expect(Object.keys(serializedMetrics._aws.CloudWatchMetrics[0].Metrics[0])).toContain('Unit');
     });
 
-    test('Should be StorageResolution 1 if MetricResolution is set to `High`',()=>{
+    test('Should be StorageResolution `1` if MetricResolution is set to `High`',()=>{
       const metrics = new Metrics();
       metrics.addMetric('test_name', MetricUnits.Seconds, 10, MetricResolution.High);
       const serializedMetrics = metrics.serializeMetrics();
@@ -603,7 +608,7 @@ describe('Class: Metrics', () => {
       expect(serializedMetrics._aws.CloudWatchMetrics[0].Metrics[0].StorageResolution).toBe(1);
     });
 
-    test('Should be StorageResolution 1 if MetricResolution is set to `1`',()=>{
+    test('Should be StorageResolution `1` if MetricResolution is set to `1`',()=>{
       const metrics = new Metrics();
       metrics.addMetric('test_name', MetricUnits.Seconds, 10, 1);
       const serializedMetrics = metrics.serializeMetrics();

packages/metrics/tests/unit/middleware/middy.test.ts

@@ -321,7 +321,7 @@ describe('Middy middleware', () => {
   });
   describe('Metrics resolution', () => {
 
-    test('should use metric resolution `Standard, 60` if `Standard` is set', async () => {
+    test('serialized metrics in EMF format should not contain `StorageResolution` as key if `60` is set', async () => {
       // Prepare
       const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });
 
@@ -346,7 +346,6 @@ describe('Middy middleware', () => {
                 Metrics: [{
                   Name: 'successfulBooking',
                   Unit: 'Count',
-                  StorageResolution: 60,
                 }],              
               },
             ],
@@ -357,7 +356,7 @@ describe('Middy middleware', () => {
       );
     });
 
-    test('should use metric resolution `High, 1` if `High` is set', async () => {
+    test('Should be StorageResolution `1` if MetricResolution is set to `High`', async () => {
       // Prepare
       const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });