chore(cicd): cdk examples and e2e tests for metrics (#326)

* propose global example and e2e test

* move to a real test

Author: flochaz

examples/cdk/.gitignore

@@ -0,0 +1,8 @@
+*.js
+!jest.config.js
+*.d.ts
+node_modules
+
+# CDK asset staging directory
+.cdk.staging
+cdk.out

examples/cdk/.npmignore

@@ -0,0 +1,6 @@
+*.ts
+!*.d.ts
+
+# CDK asset staging directory
+.cdk.staging
+cdk.out

examples/cdk/README.md

@@ -0,0 +1,14 @@
+# Welcome to your CDK TypeScript project!
+
+This is a blank project for TypeScript development with CDK.
+
+The `cdk.json` file tells the CDK Toolkit how to execute your app.
+
+## Useful commands
+
+ * `npm run build`   compile typescript to js
+ * `npm run watch`   watch for changes and compile
+ * `npm run test`    perform the jest unit tests
+ * `cdk deploy`      deploy this stack to your default AWS account/region
+ * `cdk diff`        compare deployed stack with current state
+ * `cdk synth`       emits the synthesized CloudFormation template

examples/cdk/bin/cdk-app.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import 'source-map-support/register';
+import * as cdk from 'aws-cdk-lib';
+import { CdkAppStack } from '../lib/example-stack';
+
+const app = new cdk.App();
+new CdkAppStack(app, 'CdkAppStack', {
+  /* If you don't specify 'env', this stack will be environment-agnostic.
+   * Account/Region-dependent features and context lookups will not work,
+   * but a single synthesized template can be deployed anywhere. */
+
+  /* Uncomment the next line to specialize this stack for the AWS Account
+   * and Region that are implied by the current CLI configuration. */
+  // env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION },
+
+  /* Uncomment the next line if you know exactly what Account and Region you
+   * want to deploy the stack to. */
+  // env: { account: '123456789012', region: 'us-east-1' },
+
+  /* For more information, see https://docs.aws.amazon.com/cdk/latest/guide/environments.html */
+});

examples/cdk/cdk.json

@@ -0,0 +1,26 @@
+{
+  "app": "npx ts-node --prefer-ts-exts bin/cdk-app.ts",
+  "watch": {
+    "include": [
+      "**"
+    ],
+    "exclude": [
+      "README.md",
+      "cdk*.json",
+      "**/*.d.ts",
+      "**/*.js",
+      "tsconfig.json",
+      "package*.json",
+      "yarn.lock",
+      "node_modules",
+      "test"
+    ]
+  },
+  "context": {
+    "@aws-cdk/aws-apigateway:usagePlanKeyOrderInsensitiveId": true,
+    "@aws-cdk/core:stackRelativeExports": true,
+    "@aws-cdk/aws-rds:lowercaseDbIdentifier": true,
+    "@aws-cdk/aws-lambda:recognizeVersionProps": true,
+    "@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021": true
+  }
+}

examples/cdk/jest.config.js

@@ -0,0 +1,8 @@
+module.exports = {
+  testEnvironment: 'node',
+  roots: ['<rootDir>/test'],
+  testMatch: ['**/*.test.ts'],
+  transform: {
+    '^.+\\.tsx?$': 'ts-jest'
+  }
+};

examples/cdk/lib/example-stack.MyFunction.ts

@@ -0,0 +1,61 @@
+import { Context } from 'aws-lambda';
+import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
+import { Logger } from '@aws-lambda-powertools/logger';
+import { Tracer } from '@aws-lambda-powertools/tracer';
+
+const namespace = 'CDKExample';
+const serviceName = 'MyFunctionWithStandardHandler';
+
+const metrics = new Metrics({ namespace: namespace, service: serviceName });
+const logger = new Logger({ logLevel: 'INFO', serviceName: serviceName });
+const tracer = new Tracer({ serviceName: serviceName });
+
+export const handler = async (_event: unknown, context: Context): Promise<unknown> => {
+  // Since we are in manual mode we need to create the handler segment (the 4 lines below would be done for you by decorator/middleware)
+  // we do it at the beginning because we want to trace the whole duration of the handler
+  const segment = tracer.getSegment(); // This is the facade segment (the one that is created by Lambda & that can't be manipulated)
+  const handlerSegment = segment.addNewSubsegment(`## ${context.functionName}`);
+  // TODO: expose tracer.annotateColdStart()
+  tracer.putAnnotation('ColdStart', Tracer.coldStart);
+
+  // ### Experiment logger
+  logger.addPersistentLogAttributes({
+    testKey: 'testValue',
+  });
+  logger.debug('This is an DEBUG log'); // Won't show by default
+  logger.info('This is an INFO log');
+  logger.warn('This is an WARN log');
+  logger.error('This is an ERROR log');
+
+  // ### Experiment metrics
+  metrics.captureColdStartMetric();
+  metrics.raiseOnEmptyMetrics();
+  metrics.setDefaultDimensions({ environment: 'example', type: 'standardFunction' });
+  metrics.addMetric('test-metric', MetricUnits.Count, 10);
+
+  const metricWithItsOwnDimensions = metrics.singleMetric();
+  metricWithItsOwnDimensions.addDimension('InnerDimension', 'true');
+  metricWithItsOwnDimensions.addMetric('single-metric', MetricUnits.Percent, 50);
+
+  metrics.purgeStoredMetrics();
+  metrics.raiseOnEmptyMetrics();
+
+  // ### Experiment tracer
+
+  tracer.putAnnotation('Myannotation', 'My annotation\'s value');
+
+  // Create subsegment & set it as active
+  const subsegment = handlerSegment.addNewSubsegment('MySubSegment');
+
+  try {
+    throw new Error('test');
+    // Add the response as metadata
+  } catch (err) {
+    // Add the error as metadata
+    subsegment.addError(err as Error, false);
+  }
+
+  // Close subsegment
+  subsegment.close();
+  handlerSegment.close();
+};

examples/cdk/lib/example-stack.MyFunctionWithDecorator.ts

@@ -0,0 +1,63 @@
+import { Tracer } from '@aws-lambda-powertools/tracer';
+import { Callback, Context } from 'aws-lambda';
+import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
+import { Logger } from '@aws-lambda-powertools/logger';
+
+const namespace = 'CDKExample';
+const serviceName = 'MyFunctionWithDecorator';
+
+const metrics = new Metrics({ namespace: namespace, service: serviceName });
+const logger = new Logger({ logLevel: 'INFO', serviceName: serviceName });
+const tracer = new Tracer({ serviceName: serviceName });
+
+export class MyFunctionWithDecorator {
+  @tracer.captureLambdaHanlder()
+  @logger.injectLambdaContext()
+  @metrics.logMetrics({
+    captureColdStartMetric: true,
+    raiseOnEmptyMetrics: true,
+    defaultDimensions: { environment: 'example', type: 'withDecorator' },
+  })
+  public handler(_event: unknown, _context: Context, _callback: Callback<unknown>): void | Promise<unknown> {
+    // ### Experiment logger
+    logger.addPersistentLogAttributes({
+      testKey: 'testValue',
+    });
+    logger.debug('This is an DEBUG log'); // Won't show by default
+    logger.info('This is an INFO log');
+    logger.warn('This is an WARN log');
+    logger.error('This is an ERROR log');
+
+    // ### Experiment metrics
+    metrics.addMetric('test-metric', MetricUnits.Count, 10);
+
+    const metricWithItsOwnDimensions = metrics.singleMetric();
+    metricWithItsOwnDimensions.addDimension('InnerDimension', 'true');
+    metricWithItsOwnDimensions.addMetric('single-metric', MetricUnits.Percent, 50);
+
+    // ### Experiment tracer
+    tracer.putAnnotation('Myannotation', 'My annotation\'s value');
+
+    // Create subsegment & set it as active
+    const segment = tracer.getSegment(); // This is the facade segment (the one that is created by Lambda & that can't be manipulated)
+    const subsegment = segment.addNewSubsegment('MySubSegment');
+
+    tracer.setSegment(subsegment);
+    // TODO: Add the ColdStart annotation !!! NOT POSSIBLE
+    // tracer.putAnnotation('ColdStart', tracer);
+
+    try {
+      throw new Error('test');
+      // Add the response as metadata
+    } catch (err) {
+      // Add the error as metadata
+      subsegment.addError(err as Error, false);
+    }
+
+    // Close subsegment
+    subsegment.close();
+  }
+}
+
+export const handlerClass = new MyFunctionWithDecorator();
+export const handler = handlerClass.handler;

examples/cdk/lib/example-stack.MyFunctionWithMiddy.ts

@@ -0,0 +1,43 @@
+import middy from '@middy/core'
+import { Callback, Context } from 'aws-lambda';
+import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
+
+const metrics = new Metrics({ namespace: 'CDKExample', service: 'withMiddy' }); // Sets metric namespace, and service as a metric dimension
+
+type CustomEvent = {
+  throw: boolean
+};
+
+class MyFunctionWithDecorator {
+
+  @metrics.logMetrics({ captureColdStartMetric: true })
+  public handler(_event: CustomEvent, _context: Context, _callback: Callback<unknown>): void | Promise<unknown> {
+    metrics.addMetric('test-metric', MetricUnits.Count, 10);
+    if (_event.throw) {
+      throw new Error('Test error');
+    }
+  }
+}
+
+const handler = middy(async (_event, _context) => {
+
+  const handlerClass = new MyFunctionWithDecorator();
+
+  return handlerClass.handler(_event, _context, () => console.log('Lambda invoked!'));
+});
+
+handler.before(async (_request) => {
+  metrics.addMetric('beforeHandlerCalled', MetricUnits.Count, 1);
+});
+
+handler.after(async (_request) => {
+  // Won't be flushed since happens after 
+  metrics.addMetric('afterHandlerCalled', MetricUnits.Count, 1);
+
+});
+
+handler.onError(async (_request) => {
+  metrics.addMetric('onErrorHandlerCalled', MetricUnits.Count, 1);
+});
+
+module.exports = { handler };

examples/cdk/lib/example-stack.ts

@@ -0,0 +1,86 @@
+import { Stack, StackProps, custom_resources, aws_iam } from 'aws-cdk-lib';
+import { Events } from '@aws-lambda-powertools/commons';
+import { Construct } from 'constructs';
+import * as lambda from 'aws-cdk-lib/aws-lambda-nodejs';
+import { Tracing } from 'aws-cdk-lib/aws-lambda';
+
+export class CdkAppStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    const myFunctionWithStandardFunctions = new lambda.NodejsFunction(this, 'MyFunction', { tracing: Tracing.ACTIVE });
+    const myFunctionWithDecorator = new lambda.NodejsFunction(this, 'MyFunctionWithDecorator', {
+      tracing: Tracing.ACTIVE,
+    });
+    const myFunctionWithWithMiddleware = new lambda.NodejsFunction(this, 'MyFunctionWithMiddy', {
+      tracing: Tracing.ACTIVE,
+    });
+
+    // Invoke all functions twice
+    for (let i = 0; i < 2; i++) {
+      new custom_resources.AwsCustomResource(this, `Invoke-std-func-${i}`, {
+        onUpdate: {
+          service: 'Lambda',
+          action: 'invoke',
+          physicalResourceId: custom_resources.PhysicalResourceId.of(new Date().toISOString()),
+          parameters: {
+            FunctionName: myFunctionWithStandardFunctions.functionName,
+            InvocationType: 'RequestResponse',
+            Payload: JSON.stringify(Events.Custom.CustomEvent),
+          }
+        },
+        policy: custom_resources.AwsCustomResourcePolicy.fromStatements([
+          new aws_iam.PolicyStatement({
+            effect: aws_iam.Effect.ALLOW,
+            resources: [
+              myFunctionWithStandardFunctions.functionArn,
+            ],
+            actions: ['lambda:InvokeFunction'],
+          }),
+        ]),
+      });
+      new custom_resources.AwsCustomResource(this, `Invoke-dec-func-${i}`, {
+        onUpdate: {
+          service: 'Lambda',
+          action: 'invoke',
+          physicalResourceId: custom_resources.PhysicalResourceId.of(new Date().toISOString()),
+          parameters: {
+            FunctionName: myFunctionWithDecorator.functionName,
+            InvocationType: 'RequestResponse',
+            Payload: JSON.stringify(Events.Custom.CustomEvent),
+          }
+        },
+        policy: custom_resources.AwsCustomResourcePolicy.fromStatements([
+          new aws_iam.PolicyStatement({
+            effect: aws_iam.Effect.ALLOW,
+            resources: [
+              myFunctionWithDecorator.functionArn,
+            ],
+            actions: ['lambda:InvokeFunction'],
+          }),
+        ]),
+      });
+      new custom_resources.AwsCustomResource(this, `Invoke-middy-func-${i}`, {
+        onUpdate: {
+          service: 'Lambda',
+          action: 'invoke',
+          physicalResourceId: custom_resources.PhysicalResourceId.of(new Date().toISOString()),
+          parameters: {
+            FunctionName: myFunctionWithWithMiddleware.functionName,
+            InvocationType: 'RequestResponse',
+            Payload: JSON.stringify(Events.Custom.CustomEvent),
+          }
+        },
+        policy: custom_resources.AwsCustomResourcePolicy.fromStatements([
+          new aws_iam.PolicyStatement({
+            effect: aws_iam.Effect.ALLOW,
+            resources: [
+              myFunctionWithWithMiddleware.functionArn,
+            ],
+            actions: ['lambda:InvokeFunction'],
+          }),
+        ]),
+      });
+    }
+  }
+}