From 646a9e849953191cb32264ea7392f404fc81d95d Mon Sep 17 00:00:00 2001 From: alex-m-aws <72253719+alex-m-aws@users.noreply.github.com> Date: Mon, 17 Jan 2022 14:22:28 +0000 Subject: [PATCH] docs: Improve examples/cdk/README.md (#467) * Improve examples/cdk/README.md * Address PR comments on README update * Addres PR comments #2 --- examples/cdk/README.md | 30 ++++++++++++------- examples/cdk/bin/cdk-app.ts | 2 +- packages/metrics/src/Metrics.ts | 4 +-- .../tests/e2e/decorator.test.MyFunction.ts | 2 +- .../e2e/standardFunctions.test.MyFunction.ts | 2 +- 5 files changed, 25 insertions(+), 15 deletions(-) diff --git a/examples/cdk/README.md b/examples/cdk/README.md index 3247665185..c6bcbbbe3c 100644 --- a/examples/cdk/README.md +++ b/examples/cdk/README.md @@ -1,14 +1,24 @@ -# Welcome to your CDK TypeScript project! +# AWS Lambda Powertools (TypeScript) examples in CDK -This is a blank project for TypeScript development with CDK. +This is a deployable CDK app that deploys AWS Lambda functions as part of a CloudFormation stack. These Lambda functions use the utilities made available as part of AWS Lambda Powertools (TypeScript) to demonstrate their usage. -The `cdk.json` file tells the CDK Toolkit how to execute your app. +You will need to have a valid AWS Account in order to deploy these resources. These resources may incur costs to your AWS Account. The cost from **some services** are covered by the [AWS Free Tier](https://aws.amazon.com/free/?all-free-tier.sort-by=item.additionalFields.SortRank&all-free-tier.sort-order=asc&awsf.Free%20Tier%20Types=*all&awsf.Free%20Tier%20Categories=*all) but not all of them. If you don't have an AWS Account follow [these instructions to create one](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/). -## Useful commands +The example functions, located in the `lib` folder, are invoked automatically, twice, when deployed using the CDK construct defined in `lib/example-function.ts`. The first invocation demonstrates the effect on logs/metrics/annotations when the Lambda function has a cold start, and the latter without a cold start. - * `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 +## Deploying the stack + + * Ensure that CDK v2 is installed globally on your machine (if not, run `npm install -g aws-cdk`) + * Navigate to this location of the repo in your terminal (`examples/cdk`) + * `npm install` + * `cdk deploy --all --profile ` + +Note: Prior to deploying you may need to run `cdk bootstrap aws:/// --profile ` if you have not already bootstrapped your account for CDK. + +## Viewing Utility Outputs + +All utility outputs can be viewed in the Amazon CloudWatch console. + + * `Logger` output can be found in Logs > Log groups + * `Metrics` output can be found in Metrics > All metrics > CdkExample + * `Tracer` output can be found in X-Ray traces > Traces diff --git a/examples/cdk/bin/cdk-app.ts b/examples/cdk/bin/cdk-app.ts index bbcff99e06..9d8060953b 100644 --- a/examples/cdk/bin/cdk-app.ts +++ b/examples/cdk/bin/cdk-app.ts @@ -4,4 +4,4 @@ import * as cdk from 'aws-cdk-lib'; import { CdkAppStack } from '../lib/example-stack'; const app = new cdk.App(); -new CdkAppStack(app, 'CdkAppStack', {}); \ No newline at end of file +new CdkAppStack(app, 'LambdaPowertoolsTypeScript-ExamplesCdkStack', {}); \ No newline at end of file diff --git a/packages/metrics/src/Metrics.ts b/packages/metrics/src/Metrics.ts index 3afb21a6f4..764d840b10 100644 --- a/packages/metrics/src/Metrics.ts +++ b/packages/metrics/src/Metrics.ts @@ -210,7 +210,7 @@ class Metrics implements MetricsInterface { * import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics'; * import { Callback, Context } from 'aws-lambda'; * - * const metrics = new Metrics({namespace:"CDKExample", serviceName:"withDecorator"}); + * const metrics = new Metrics({namespace:"CdkExample", serviceName:"withDecorator"}); * * export class MyFunctionWithDecorator { * @@ -267,7 +267,7 @@ class Metrics implements MetricsInterface { * ```typescript * import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics'; * - * const metrics = new Metrics({namespace: "CDKExample", serviceName: "MyFunction"}); // Sets metric namespace, and service as a metric dimension + * const metrics = new Metrics({namespace: "CdkExample", serviceName: "MyFunction"}); // Sets metric namespace, and service as a metric dimension * * export const handler = async (_event: any, _context: any) => { * metrics.addMetric('test-metric', MetricUnits.Count, 10); diff --git a/packages/metrics/tests/e2e/decorator.test.MyFunction.ts b/packages/metrics/tests/e2e/decorator.test.MyFunction.ts index 1c8fe06209..60c007c040 100644 --- a/packages/metrics/tests/e2e/decorator.test.MyFunction.ts +++ b/packages/metrics/tests/e2e/decorator.test.MyFunction.ts @@ -2,7 +2,7 @@ import { Metrics, MetricUnits } from '../../src'; import { Context } from 'aws-lambda'; import { LambdaInterface } from '../../examples/utils/lambda/LambdaInterface'; -const namespace = process.env.EXPECTED_NAMESPACE ?? 'CDKExample'; +const namespace = process.env.EXPECTED_NAMESPACE ?? 'CdkExample'; const serviceName = process.env.EXPECTED_SERVICE_NAME ?? 'MyFunctionWithStandardHandler'; const metricName = process.env.EXPECTED_METRIC_NAME ?? 'MyMetric'; const metricUnit = (process.env.EXPECTED_METRIC_UNIT as MetricUnits) ?? MetricUnits.Count; diff --git a/packages/metrics/tests/e2e/standardFunctions.test.MyFunction.ts b/packages/metrics/tests/e2e/standardFunctions.test.MyFunction.ts index 732ab872b4..997b5775d9 100644 --- a/packages/metrics/tests/e2e/standardFunctions.test.MyFunction.ts +++ b/packages/metrics/tests/e2e/standardFunctions.test.MyFunction.ts @@ -1,7 +1,7 @@ import { Metrics, MetricUnits } from '../../src'; import { Context } from 'aws-lambda'; -const namespace = process.env.EXPECTED_NAMESPACE ?? 'CDKExample'; +const namespace = process.env.EXPECTED_NAMESPACE ?? 'CdkExample'; const serviceName = process.env.EXPECTED_SERVICE_NAME ?? 'MyFunctionWithStandardHandler'; const metricName = process.env.EXPECTED_METRIC_NAME ?? 'MyMetric'; const metricUnit = (process.env.EXPECTED_METRIC_UNIT as MetricUnits) ?? MetricUnits.Count;