idea-aws 3.14.1 → 3.15.0

package/dist/src/metrics.d.ts

@@ -0,0 +1,31 @@
+import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
+/**
+ * A wrapper for simple uses of CloudWatch Metrics.
+ */
+export declare class CloudWatchMetrics {
+    private metrics;
+    constructor(options?: {
+        project?: string;
+    });
+    /**
+     * Get the raw Metrics object. To use for custom purposes.
+     */
+    __raw(): Metrics;
+    /**
+     * Add an entry for the metrics.
+     */
+    addMetric(metricName: string, value?: number, unit?: MetricUnits): void;
+    /**
+     * Add a metadata useful when you want to search highly contextual information along with your metrics in your logs.
+     */
+    addMetadata(key: string, value: string): void;
+    /**
+     * Add an additional metrics dimension.
+     */
+    addDimension(name: string, value: string, defaultValue?: string): void;
+    /**
+     * Synchronous function to actually publish your metrics.
+     * It will create a new EMF blob and log it to be then ingested by Cloudwatch logs and processed for metrics creation.
+     */
+    publishStoredMetrics(): void;
+}

package/dist/src/metrics.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CloudWatchMetrics = void 0;
+const metrics_1 = require("@aws-lambda-powertools/metrics");
+/**
+ * A wrapper for simple uses of CloudWatch Metrics.
+ */
+class CloudWatchMetrics {
+    constructor(options) {
+        const project = options?.project ?? process.env.PROJECT ?? 'unknownProject';
+        this.metrics = new metrics_1.Metrics({ namespace: project });
+    }
+    /**
+     * Get the raw Metrics object. To use for custom purposes.
+     */
+    __raw() {
+        return this.metrics;
+    }
+    /**
+     * Add an entry for the metrics.
+     */
+    addMetric(metricName, value = 1, unit = metrics_1.MetricUnits.Count) {
+        this.metrics.addMetric(metricName, unit, value);
+    }
+    /**
+     * Add a metadata useful when you want to search highly contextual information along with your metrics in your logs.
+     */
+    addMetadata(key, value) {
+        this.metrics.addMetadata(key, value);
+    }
+    /**
+     * Add an additional metrics dimension.
+     */
+    addDimension(name, value, defaultValue = '-') {
+        this.metrics.addDimension(name, value ?? defaultValue);
+    }
+    /**
+     * Synchronous function to actually publish your metrics.
+     * It will create a new EMF blob and log it to be then ingested by Cloudwatch logs and processed for metrics creation.
+     */
+    publishStoredMetrics() {
+        this.metrics.publishStoredMetrics();
+    }
+}
+exports.CloudWatchMetrics = CloudWatchMetrics;

package/dist/src/resourceController.d.ts

@@ -2,6 +2,7 @@ import 'source-map-support/register';
 import { APIGatewayProxyEventV2, APIGatewayProxyEvent, Callback } from 'aws-lambda';
 import { CognitoUser, Auth0User } from 'idea-toolbox';
 import { Logger } from './logger';
+import { CloudWatchMetrics } from './metrics';
 import { GenericController, GenericControllerOptions } from './genericController';
 /**
  * An abstract class to inherit to manage API requests (AWS API Gateway) in an AWS Lambda function.
@@ -26,6 +27,7 @@ export declare abstract class ResourceController extends GenericController {
     protected returnStatusCode?: number;
     protected logger: Logger;
     protected logRequestsWithKey: string;
+    protected metrics: CloudWatchMetrics;
     protected currentLang: string;
     protected defaultLang: string;
     protected translations: any;
@@ -100,12 +102,20 @@ export declare abstract class ResourceController extends GenericController {
      * Check whether shared resource exists in the back-end (translation, template, etc.).
      * Search for the specified file path in both the Lambda function's main folder and the layers folder.
      */
-    sharedResourceExists(filePath: string): boolean;
+    protected sharedResourceExists(filePath: string): boolean;
     /**
      * Load a shared resource in the back-end (translation, template, etc.).
      * Search for the specified file path in both the Lambda function's main folder and the layers folder.
      */
-    loadSharedResource(filePath: string): string;
+    protected loadSharedResource(filePath: string): string;
+    /**
+     * Prepare the CloudWatch metrics at the beginning of a request.
+     */
+    protected prepareMetrics(): void;
+    /**
+     * Publish the CloudWatch metrics (default and custom-defined) at the end of a reqeust.
+     */
+    protected publishMetrics(statusCode: number, error?: any): void;
     /**
      * Simulate an internal API request, invoking directly the lambda and therefore saving resources.
      * @return the body of the response

package/dist/src/resourceController.js

@@ -6,6 +6,7 @@ const fs_1 = require("fs");
 const aws_sdk_1 = require("aws-sdk");
 const idea_toolbox_1 = require("idea-toolbox");
 const logger_1 = require("./logger");
+const metrics_1 = require("./metrics");
 const genericController_1 = require("./genericController");
 /**
  * An abstract class to inherit to manage API requests (AWS API Gateway) in an AWS Lambda function.
@@ -15,6 +16,7 @@ class ResourceController extends genericController_1.GenericController {
         super(event, callback, options);
         this.initError = false;
         this.logger = new logger_1.Logger();
+        this.metrics = new metrics_1.CloudWatchMetrics();
         this.templateMatcher = /{{\s?([^{}\s]*)\s?}}/g;
         ///
         /// REQUEST HANDLERS
@@ -104,6 +106,7 @@ class ResourceController extends genericController_1.GenericController {
                 platform = this.queryParams['_p'];
                 delete this.queryParams['_p'];
             }
+            this.prepareMetrics();
             // print the initial log
             const info = { principalId: this.principalId, queryParams: this.queryParams, body: this.body, version, platform };
             this.logger.info(`START: ${this.httpMethod} ${this.path}`, info);
@@ -180,9 +183,9 @@ class ResourceController extends genericController_1.GenericController {
             this.logger.info('END-FAILED', { statusCode, error: err.message || err.errorMessage });
         else
             this.logger.info('END-SUCCESS', { statusCode });
-        // if configured, store the log of the request
         if (this.logRequestsWithKey)
             this.storeLog(!err);
+        this.publishMetrics(statusCode, err);
         this.callback(null, {
             statusCode: String(statusCode),
             body: err ? JSON.stringify({ message: err.message }) : JSON.stringify(res || {}),
@@ -309,6 +312,32 @@ class ResourceController extends genericController_1.GenericController {
             path = `/opt/nodejs/assets/${filePath}`;
         return path ? (0, fs_1.readFileSync)(path, { encoding: 'utf-8' }) : null;
     }
+    /**
+     * Prepare the CloudWatch metrics at the beginning of a request.
+     */
+    prepareMetrics() {
+        this.metrics.addDimension('stage', process.env.STAGE);
+        this.metrics.addDimension('resource', process.env.RESOURCE);
+        this.metrics.addDimension('method', this.httpMethod);
+        this.metrics.addDimension('target', this.resourceId ? 'id' : 'list');
+        this.metrics.addDimension('action', this.body?.action);
+        this.metrics.addDimension('userId', this.principalId);
+        this.metrics.addMetadata('resourceId', this.resourceId);
+    }
+    /**
+     * Publish the CloudWatch metrics (default and custom-defined) at the end of a reqeust.
+     */
+    publishMetrics(statusCode, error) {
+        this.metrics.addMetric('request');
+        this.metrics.addMetric('statusCode', statusCode);
+        if (error) {
+            this.metrics.addMetric('failed');
+            this.metrics.addMetadata('errorMessage', error.name);
+        }
+        else
+            this.metrics.addMetric('success');
+        this.metrics.publishStoredMetrics();
+    }
     ///
     /// MANAGE INTERNAL API REQUESTS (lambda invokes masked as API requests)
     ///

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "idea-aws",
-  "version": "3.14.1",
+  "version": "3.15.0",
   "description": "AWS wrappers to use in IDEA's back-ends",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,7 +26,8 @@
     "translate",
     "cognito",
     "comprehend",
-    "secretsManager"
+    "secretsManager",
+    "cloudWatch"
   ],
   "author": "ITER IDEA <info@iter-idea.com> (https://iter-idea.com)",
   "license": "ISC",
@@ -35,7 +36,8 @@
   },
   "homepage": "https://iter-idea.github.io/IDEA-AWS",
   "dependencies": {
-    "idea-toolbox": "^6.6.2",
+    "@aws-lambda-powertools/metrics": "^1.4.1",
+    "idea-toolbox": "^6.6.3",
     "nanoid": "^3.3.4",
     "nodemailer": "^6.7.7",
     "shortid": "^2.2.16",