idea-aws 3.14.1 → 3.15.1

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 ?? '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.
@@ -15,17 +16,22 @@ export declare abstract class ResourceController extends GenericController {
     protected principalId: string;
     protected cognitoUser: CognitoUser;
     protected auth0User: Auth0User;
+    protected project: string;
     protected stage: string;
     protected httpMethod: string;
     protected body: any;
     protected queryParams: any;
-    protected resource: string;
+    protected resourcePath: string;
     protected path: string;
     protected pathParameters: any;
+    protected resource: string;
     protected resourceId: string;
+    protected clientVersion: string;
+    protected clientPlatform: string;
     protected returnStatusCode?: number;
     protected logger: Logger;
     protected logRequestsWithKey: string;
+    protected metrics: CloudWatchMetrics;
     protected currentLang: string;
     protected defaultLang: string;
     protected translations: any;
@@ -100,12 +106,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.
@@ -14,7 +15,13 @@ class ResourceController extends genericController_1.GenericController {
     constructor(event, callback, options = {}) {
         super(event, callback, options);
         this.initError = false;
+        this.project = process?.env?.PROJECT;
+        this.stage = process?.env?.STAGE;
+        this.resource = process?.env?.RESOURCE;
+        this.clientVersion = '?';
+        this.clientPlatform = '?';
         this.logger = new logger_1.Logger();
+        this.metrics = new metrics_1.CloudWatchMetrics({ project: this.project });
         this.templateMatcher = /{{\s?([^{}\s]*)\s?}}/g;
         ///
         /// REQUEST HANDLERS
@@ -95,17 +102,23 @@ class ResourceController extends genericController_1.GenericController {
                 this.initFromEventV1(event, options);
             this.logRequestsWithKey = options.logRequestsWithKey;
             // acquire some info about the client, if available
-            let version = '?', platform = '?';
             if (this.queryParams['_v']) {
-                version = this.queryParams['_v'];
+                this.clientVersion = this.queryParams['_v'];
                 delete this.queryParams['_v'];
             }
             if (this.queryParams['_p']) {
-                platform = this.queryParams['_p'];
+                this.clientPlatform = 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 };
+            const info = {
+                principalId: this.principalId,
+                queryParams: this.queryParams,
+                body: this.body,
+                version: this.clientVersion,
+                platform: this.clientPlatform
+            };
             this.logger.info(`START: ${this.httpMethod} ${this.path}`, info);
         }
         catch (err) {
@@ -120,9 +133,9 @@ class ResourceController extends genericController_1.GenericController {
         this.principalId = contextFromAuthorizer.principalId ?? contextFromAuthorizer.sub ?? null;
         this.cognitoUser = authorizer.jwt?.claims ? new idea_toolbox_1.CognitoUser(authorizer.jwt?.claims) : null;
         this.auth0User = contextFromAuthorizer.auth0User ? new idea_toolbox_1.Auth0User(contextFromAuthorizer.auth0User) : null;
-        this.stage = event.requestContext.stage;
+        this.stage = this.stage ?? event.requestContext.stage;
         this.httpMethod = event.requestContext.http.method;
-        this.resource = event.routeKey.replace('+', ''); // {proxy+} -> {proxy}
+        this.resourcePath = event.routeKey.replace('+', ''); // {proxy+} -> {proxy}
         this.path = event.rawPath;
         this.pathParameters = {};
         for (const param in event.pathParameters)
@@ -142,9 +155,9 @@ class ResourceController extends genericController_1.GenericController {
         this.principalId = this.claims.sub;
         this.cognitoUser = this.principalId ? new idea_toolbox_1.CognitoUser(this.claims) : null;
         this.auth0User = null;
-        this.stage = event.requestContext.stage;
+        this.stage = this.stage ?? event.requestContext.stage;
         this.httpMethod = event.httpMethod;
-        this.resource = event.resource.replace('+', ''); // {proxy+} -> {proxy}
+        this.resourcePath = event.resource.replace('+', ''); // {proxy+} -> {proxy}
         this.path = event.path;
         this.pathParameters = {};
         for (const param in event.pathParameters)
@@ -180,9 +193,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 || {}),
@@ -277,7 +290,7 @@ class ResourceController extends genericController_1.GenericController {
         const log = new idea_toolbox_1.APIRequestLog({
             logId: this.logRequestsWithKey,
             userId: this.principalId,
-            resource: this.resource,
+            resource: this.resourcePath,
             path: this.path,
             resourceId: this.resourceId,
             method: this.httpMethod,
@@ -309,6 +322,34 @@ 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', this.stage);
+        this.metrics.addDimension('resource', this.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.addDimension('clientVersion', this.clientVersion);
+        this.metrics.addDimension('clientPlatform', this.clientPlatform);
+        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.1",
   "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",