feat: add metrics

packages/logger/src/Logger.ts

@@ -6,15 +6,15 @@ import { ConfigServiceInterface, EnvironmentVariablesService } from './config';
 import {
   Environment,
   HandlerMethodDecorator,
-  PowertoolLogData,
+  LambdaFunctionContext,
   LogAttributes,
   ClassThatLogs,
   LoggerOptions,
+  LogItemExtraInput,
+  LogItemMessage,
   LogLevel,
   LogLevelThresholds,
-  LambdaFunctionContext,
-  LogItemMessage,
-  LogItemExtraInput,
+  PowertoolLogData,
 } from '../types';
 import { LogFormatterInterface, PowertoolLogFormatter } from './formatter';
 
@@ -33,7 +33,7 @@ class Logger implements ClassThatLogs {
   private logLevel?: LogLevel;
 
   private readonly logLevelThresholds: LogLevelThresholds = {
-    'DEBUG' : 8,
+    'DEBUG': 8,
     'INFO': 12,
     'WARN': 16,
     'ERROR': 20
@@ -99,7 +99,7 @@ class Logger implements ClassThatLogs {
   }
 
   public injectLambdaContext(): HandlerMethodDecorator {
-    return (target, propertyKey, descriptor ) => {
+    return (target, propertyKey, descriptor) => {
       const originalMethod = descriptor.value;
 
       descriptor.value = (event, context, callback) => {
@@ -166,7 +166,7 @@ class Logger implements ClassThatLogs {
       const attributes = (item instanceof Error) ? { error: item } : item;
       logItem.addAttributes(attributes);
     });
-    
+
     return logItem;
   }
 
@@ -228,7 +228,7 @@ class Logger implements ClassThatLogs {
   }
 
   private setCustomConfigService(customConfigService?: ConfigServiceInterface): void {
-    this.customConfigService = customConfigService? customConfigService : undefined;
+    this.customConfigService = customConfigService ? customConfigService : undefined;
   }
 
   private setEnvVarsService(): void {
@@ -298,7 +298,7 @@ class Logger implements ClassThatLogs {
       sampleRateValue: this.getSampleRateValue(),
       serviceName: serviceName || this.getCustomConfigService()?.getServiceName() || this.getEnvVarsService().getServiceName(),
       xRayTraceId: this.getEnvVarsService().getXrayTraceId(),
-    }, persistentLogAttributes );
+    }, persistentLogAttributes);
   }
 
   private shouldPrint(logLevel: LogLevel): boolean {

packages/metrics/README.md

@@ -0,0 +1,188 @@
+# `Metrics`
+
+
+##  Usage
+
+```bash
+npm run test
+
+npm run example:hello-world
+npm run example:manual-flushing
+npm run example:dimensions
+npm run example:default-dimensions
+npm run example:empty-metrics
+npm run example:single-metric
+npm run example:cold-start
+```
+
+### Getting started
+
+Metrics has two global settings that will be used across all metrics emitted:
+
+|Setting|Description|Environment Variable|Constructor Parameter|
+|---|---|---|---|
+|Metric namespace|Logical container where all metrics will be placed e.g. ServerlessAirline|POWERTOOLS_METRICS_NAMESPACE|namespace|
+|Service|Optionally, sets service metric dimension across all metrics e.g. payment|POWERTOOLS_SERVICE_NAME|service|
+
+```typescript
+// Import the library
+import { Metrics, MetricUnits } from '../src';
+// When going public, it will be something like: import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
+
+process.env.POWERTOOLS_METRICS_NAMESPACE = 'hello-world';
+process.env.POWERTOOLS_SERVICE_NAME = 'hello-world-service';
+
+// Instantiate the Logger with default configuration
+const metrics = new Metrics();
+
+// Add an example Metric
+metrics.addMetric('test-metric', MetricUnits.Count, 10);
+
+//Print resulting data
+const metricsObject = metrics.serializeMetrics();
+metrics.clearMetrics();
+console.log(JSON.stringify(metricsObject));
+
+```
+
+<details>
+ <summary>Click to expand and see the logs outputs</summary>
+
+```bash
+
+{
+  "_aws":{
+  "Timestamp":1625587915573,
+  "CloudWatchMetrics":
+    [
+      {
+        "Namespace":"hello-world",
+        "Dimensions":[["service"]],
+        "Metrics":
+          [
+            {
+              "Name":"test-metric",
+              "Unit":"Count"
+            }
+          ]
+      }
+    ]
+  },
+  "service":"hello-world-service",
+  "test-metric":10
+}
+
+```
+</details>
+
+With decorators:
+
+```typescript
+
+import { Metrics, MetricUnits } from '../src';
+
+process.env.POWERTOOLS_METRICS_NAMESPACE = 'hello-world';
+process.env.POWERTOOLS_SERVICE_NAME = 'hello-world-service';
+
+// Instantiate the Logger with default configuration
+const metrics = new Metrics();
+
+class Lambda implements LambdaInterface {
+
+  @metrics.logMetrics()
+  public handler<TEvent, TResult>(_event: TEvent, _context: Context, _callback: Callback<TResult>): void | Promise<TResult> {
+    metrics.addDimension('OuterDimension', 'true');
+    metrics.addMetric('test-metric', MetricUnits.Count, 10);
+  }
+
+}
+
+```
+
+### Capturing cold start
+
+By default the cold start metric is not captured, it can however be enabled using a parameter passed to the logMetrics decorator
+
+
+
+```typescript
+
+import { Metrics, MetricUnits } from '../src';
+
+process.env.POWERTOOLS_METRICS_NAMESPACE = 'hello-world';
+process.env.POWERTOOLS_SERVICE_NAME = 'hello-world-service';
+
+// Instantiate the Logger with default configuration
+const metrics = new Metrics();
+
+class Lambda implements LambdaInterface {
+
+  @metrics.logMetrics({ captureColdStartMetric: true }))
+  public handler<TEvent, TResult>(_event: TEvent, _context: Context, _callback: Callback<TResult>): void | Promise<TResult> {
+    metrics.addDimension('OuterDimension', 'true');
+    metrics.addMetric('test-metric', MetricUnits.Count, 10);
+  }
+
+}
+
+```
+> Please note, we do not emit a 0 value for the ColdStart metric, for cost reasons
+<details>
+ <summary>Click to expand and see the logs outputs</summary>
+
+```bash
+
+{
+  "_aws":{
+  "Timestamp":1625587915572,
+  "CloudWatchMetrics":
+    [
+      {
+        "Namespace":"hello-world",
+        "Dimensions":[[
+          "service","function_name"
+        ]],
+        "Metrics":
+          [
+            {
+              "Name":"ColdStart",
+              "Unit":"Count"
+            }
+          ]
+      }
+    ]
+  },
+  "service":"hello-world-service",
+  "function_name":"foo-bar-function",
+  "ColdStart":1
+}
+{
+  "_aws":{
+  "Timestamp":1625587915573,
+  "CloudWatchMetrics":
+    [
+      {
+        "Namespace":"hello-world",
+        "Dimensions":[["service"]],
+        "Metrics":
+          [
+            {
+              "Name":"test-metric",
+              "Unit":"Count"
+            }
+          ]
+      }
+    ]
+  },
+  "service":"hello-world-service",
+  "test-metric":10
+}
+
+```
+</details>
+If it's a cold start invocation, this feature will:
+
+- Create a separate EMF blob solely containing a metric named ColdStart
+- Add function_name and service dimensions
+
+This has the advantage of keeping cold start metric separate from your application metrics, where you might have unrelated dimensions.

packages/metrics/examples/cold-start.ts

@@ -0,0 +1,26 @@
+import * as dummyEvent from '../../../tests/resources/events/custom/hello-world.json';
+import { context as dummyContext } from '../../../tests/resources/contexts/hello-world';
+import { LambdaInterface } from './utils/lambda/LambdaInterface';
+import { populateEnvironmentVariables } from '../tests/helpers';
+import { Callback, Context } from 'aws-lambda/handler';
+import { Metrics, MetricUnits } from '../src';
+
+// Populate runtime
+populateEnvironmentVariables();
+// Additional runtime variables
+process.env.POWERTOOLS_METRICS_NAMESPACE = 'hello-world';
+
+const metrics = new Metrics();
+
+class Lambda implements LambdaInterface {
+
+  @metrics.logMetrics({ captureColdStartMetric: true })
+  public handler<TEvent, TResult>(_event: TEvent, _context: Context, _callback: Callback<TResult>): void | Promise<TResult> {
+    metrics.addDimension('OuterDimension', 'true');
+    metrics.addMetric('test-metric', MetricUnits.Count, 10);
+  }
+
+}
+
+new Lambda().handler(dummyEvent, dummyContext, () => console.log('Lambda invoked!'));
+new Lambda().handler(dummyEvent, dummyContext, () => console.log('Lambda invoked again!'));

packages/metrics/examples/default-dimensions.ts

@@ -0,0 +1,33 @@
+import { populateEnvironmentVariables } from '../tests/helpers';
+
+// Populate runtime
+populateEnvironmentVariables();
+// Additional runtime variables
+process.env.POWERTOOLS_METRICS_NAMESPACE = 'hello-world';
+
+import * as dummyEvent from '../../../tests/resources/events/custom/hello-world.json';
+import { context as dummyContext } from '../../../tests/resources/contexts/hello-world';
+import { LambdaInterface } from './utils/lambda/LambdaInterface';
+import { Callback, Context } from 'aws-lambda/handler';
+import { Metrics, MetricUnits } from '../src';
+
+const metrics = new Metrics();
+
+class Lambda implements LambdaInterface {
+
+  @metrics.logMetrics({ defaultDimensions:{ 'application': 'hello-world' } })
+  public handler<TEvent, TResult>(_event: TEvent, _context: Context, _callback: Callback<TResult>): void | Promise<TResult> {
+
+    metrics.addDimension('environment', 'dev');
+    metrics.addDimension('application', 'hello-world-dev');
+    metrics.addMetric('test-metric', MetricUnits.Count, 10);
+    const metricsObject = metrics.serializeMetrics();
+    metrics.clearMetrics();
+    metrics.clearDimensions();
+    metrics.addMetric('new-test-metric', MetricUnits.Count, 5);
+    console.log(JSON.stringify(metricsObject));
+  }
+
+}
+
+new Lambda().handler(dummyEvent, dummyContext, () => console.log('Lambda invoked!'));

packages/metrics/examples/dimensions.ts

@@ -0,0 +1,28 @@
+import { populateEnvironmentVariables } from '../tests/helpers';
+
+// Populate runtime
+populateEnvironmentVariables();
+// Additional runtime variables
+process.env.POWERTOOLS_METRICS_NAMESPACE = 'hello-world';
+
+import * as dummyEvent from '../../../tests/resources/events/custom/hello-world.json';
+import { context as dummyContext } from '../../../tests/resources/contexts/hello-world';
+import { LambdaInterface } from './utils/lambda/LambdaInterface';
+import { Callback, Context } from 'aws-lambda/handler';
+import { Metrics, MetricUnits } from '../src';
+
+const metrics = new Metrics();
+
+class Lambda implements LambdaInterface {
+
+  @metrics.logMetrics()
+  public handler<TEvent, TResult>(_event: TEvent, _context: Context, _callback: Callback<TResult>): void | Promise<TResult> {
+
+    metrics.addDimension('environment', 'dev');
+    metrics.addMetric('test-metric', MetricUnits.Count, 10);
+
+  }
+
+}
+
+new Lambda().handler(dummyEvent, dummyContext, () => console.log('Lambda invoked!'));

packages/metrics/examples/empty-metrics.ts

@@ -0,0 +1,25 @@
+import { populateEnvironmentVariables } from '../tests/helpers';
+
+// Populate runtime
+populateEnvironmentVariables();
+// Additional runtime variables
+process.env.POWERTOOLS_METRICS_NAMESPACE = 'hello-world';
+
+import * as dummyEvent from '../../../tests/resources/events/custom/hello-world.json';
+import { context as dummyContext } from '../../../tests/resources/contexts/hello-world';
+import { LambdaInterface } from './utils/lambda/LambdaInterface';
+import { Callback, Context } from 'aws-lambda/handler';
+import { Metrics } from '../src';
+
+const metrics = new Metrics();
+
+class Lambda implements LambdaInterface {
+
+  @metrics.logMetrics({ raiseOnEmptyMetrics: true })
+  public handler<TEvent, TResult>(_event: TEvent, _context: Context, _callback: Callback<TResult>): void | Promise<TResult> {
+
+  }
+
+}
+
+new Lambda().handler(dummyEvent, dummyContext, () => console.log('Lambda invoked!'));