Add examples

Author: flochaz

.gitignore

@@ -18,6 +18,7 @@ node_modules
 # Build output
 dist
 lib
+!examples/cdk/lib
 
 # Coverage directory
 coverage

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,57 @@
+import {Metrics, MetricUnits} from '@aws-lambda-powertools/metrics';
+import {Logger} from '@aws-lambda-powertools/logger';
+import {Tracer} from '@aws-lambda-powertools/tracer';
+import { Subsegment } from 'aws-xray-sdk-core';
+
+
+
+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: any, context: any) => {
+  // ### 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 = new Subsegment('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();
+};

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

@@ -0,0 +1,62 @@
+import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
+import { Logger, createLogger } from '@aws-lambda-powertools/logger';
+import { Tracer } from '@aws-lambda-powertools/tracer';
+import { Subsegment } from 'aws-xray-sdk-core';
+import { Callback, Context } from 'aws-lambda';
+
+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: any, _context: Context, _callback: Callback<any>): void | Promise<any> {
+    // ### 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 subsegment = new Subsegment('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,39 @@
+import middy from '@middy/core'
+import {Metrics, MetricUnits} from '@aws-lambda-powertools/metrics';
+import { Callback, Context } from 'aws-lambda';
+
+
+const metrics = new Metrics({namespace:"CDKExample", service:"withMiddy"}); // Sets metric namespace, and service as a metric dimension
+
+class MyFunctionWithDecorator {
+
+  @metrics.logMetrics({captureColdStartMetric: true})
+  public handler(_event: any, _context: Context, _callback: Callback<any>): void | Promise<any> {
+    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, () => {});
+})
+
+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'],
+          }),
+        ]),
+      });
+    }
+  }
+}