Merge branch 'main' into fix-doc-examples

Author: Michael Brewer

docs/core/logger.md

@@ -112,7 +112,7 @@ Key | Example
 
         logger.addContext(context);
         
-        logger.info("This is an INFO log with some context");
+        logger.info('This is an INFO log with some context');
 
     };
     ```
@@ -395,7 +395,7 @@ This can be useful for example if you want to enable multiple Loggers with diffe
     });
 
     // With this logger, only the ERROR logs will be printed
-    const childLogger = parentLogger.createChild({
+    const childLogger = logger.createChild({
         logLevel: 'ERROR'
     });
 
@@ -606,10 +606,10 @@ You can customize the structure (keys and values) of your log items by passing a
         },
     });
 
-    export const handler = async (event, _context): Promise<void> => {
+    export const handler = async (event, context): Promise<void> => {
 
         logger.addContext(context);
-        
+
         logger.info('This is an INFO log', { correlationIds: { myCustomCorrelationId: 'foo-bar-baz' } });
 
     };
@@ -620,7 +620,7 @@ This is how the `MyCompanyLogFormatter` (dummy name) would look like:
 === "utils/formatters/MyCompanyLogFormatter.ts"
 
     ```typescript
-    import { LogFormatter } from '@aws-lambda-powertools/logger/lib/formatter';
+    import { LogFormatter } from '@aws-lambda-powertools/logger';
     import { LogAttributes, UnformattedAttributes } from '@aws-lambda-powertools/logger/lib/types';
 
     // Replace this line with your own type

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 <YOUR_AWS_PROFILE>`
+
+Note: Prior to deploying you may need to run `cdk bootstrap aws://<YOU_AWS_ACCOUNT_ID>/<AWS_REGION> --profile <YOUR_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

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', {});
+new CdkAppStack(app, 'LambdaPowertoolsTypeScript-ExamplesCdkStack', {});

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

@@ -10,15 +10,20 @@ const metrics = new Metrics({ namespace: namespace, serviceName: serviceName });
 const logger = new Logger({ logLevel: 'INFO', serviceName: serviceName });
 const tracer = new Tracer({ serviceName: serviceName });
 
-export const handler = async (_event: unknown, context: Context): Promise<void> => {
+export const handler = async (event: unknown, context: Context): Promise<void> => {
   // 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);
+  const segment = tracer.getSegment(); // This is the facade segment (the one that is created by AWS Lambda)
+  // Create subsegment for the function & set it as active
+  const handlerSegment = segment.addNewSubsegment(`## ${process.env._HANDLER}`);
+  tracer.setSegment(handlerSegment);
 
-  // ### Experiment logger
+  // Annotate the subsegment with the cold start & serviceName
+  tracer.annotateColdStart();
+  tracer.addServiceNameAnnotation();
+
+  // ### Experiment with Logger
+  logger.addContext(context);
   logger.addPersistentLogAttributes({
     testKey: 'testValue',
   });
@@ -27,7 +32,7 @@ export const handler = async (_event: unknown, context: Context): Promise<void>
   logger.warn('This is an WARN log');
   logger.error('This is an ERROR log');
 
-  // ### Experiment metrics
+  // ### Experiment with Metrics
   metrics.captureColdStartMetric();
   metrics.throwOnEmptyMetrics();
   metrics.setDefaultDimensions({ environment: 'example', type: 'standardFunction' });
@@ -40,22 +45,29 @@ export const handler = async (_event: unknown, context: Context): Promise<void>
   metrics.publishStoredMetrics();
   metrics.throwOnEmptyMetrics();
 
-  // ### Experiment tracer
-
-  tracer.putAnnotation('Myannotation', 'My annotation\'s value');
+  // ### Experiment with Tracer
+  // This annotation & metadata will be added to the handlerSegment subsegment (## index.handler)
+  tracer.putAnnotation('awsRequestId', context.awsRequestId);
+  tracer.putMetadata('eventPayload', event);
 
-  // Create subsegment & set it as active
-  const subsegment = handlerSegment.addNewSubsegment('MySubSegment');
+  // Create another subsegment & set it as active
+  const subsegment = handlerSegment.addNewSubsegment('### MySubSegment');
+  tracer.setSegment(subsegment);
 
+  let res;
   try {
-    throw new Error('test');
-    // Add the response as metadata
+    res = { foo: 'bar' };
+    tracer.addResponseAsMetadata(res, process.env._HANDLER);
   } catch (err) {
     // Add the error as metadata
     subsegment.addError(err as Error, false);
+    throw err;
+  } finally {
+    // Close subsegments (the AWS Lambda one is closed automatically)
+    subsegment.close(); // (### MySubSegment)
+    handlerSegment.close(); // (## index.handler)
+    // Set the facade segment as active again (the one created by AWS Lambda)
+    tracer.setSegment(segment);
   }
 
-  // Close subsegment
-  subsegment.close();
-  handlerSegment.close();
 };

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

@@ -1,5 +1,6 @@
 import { Tracer } from '@aws-lambda-powertools/tracer';
-import { Callback, Context } from 'aws-lambda';
+import { Context } from 'aws-lambda';
+import { Events, LambdaInterface } from '@aws-lambda-powertools/commons';
 import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
 import { Logger } from '@aws-lambda-powertools/logger';
 
@@ -10,15 +11,16 @@ const metrics = new Metrics({ namespace: namespace, serviceName: serviceName });
 const logger = new Logger({ logLevel: 'INFO', serviceName: serviceName });
 const tracer = new Tracer({ serviceName: serviceName });
 
-export class MyFunctionWithDecorator {
+export class MyFunctionWithDecorator implements LambdaInterface {
+  // We decorate the handler with the various decorators
   @tracer.captureLambdaHandler()
   @logger.injectLambdaContext()
   @metrics.logMetrics({
     captureColdStartMetric: true,
     throwOnEmptyMetrics: true,
     defaultDimensions: { environment: 'example', type: 'withDecorator' },
   })
-  public handler(_event: unknown, _context: Context, _callback: Callback<unknown>): void | Promise<unknown> {
+  public async handler(event: typeof Events.Custom.CustomEvent, context: Context): Promise<unknown> {
     // ### Experiment logger
     logger.addPersistentLogAttributes({
       testKey: 'testValue',
@@ -36,28 +38,34 @@ export class MyFunctionWithDecorator {
     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');
+    // Service & Cold Start annotations will be added for you by the decorator/middleware
 
+    // These traces will be added to the main segment (## index.handler)
+    tracer.putAnnotation('awsRequestId', context.awsRequestId);
+    tracer.putMetadata('eventPayload', event);
+
+    // Create another subsegment & set it as active
+    const handlerSegment = tracer.getSegment(); // This is the custom segment created by Tracer for you (## index.handler)
+    const subsegment = handlerSegment.addNewSubsegment('### MySubSegment');
     tracer.setSegment(subsegment);
-    // TODO: Add the ColdStart annotation !!! NOT POSSIBLE
-    // tracer.putAnnotation('ColdStart', tracer);
 
+    let res;
     try {
-      throw new Error('test');
-      // Add the response as metadata
+      res = { foo: 'bar' };
     } catch (err) {
-      // Add the error as metadata
-      subsegment.addError(err as Error, false);
+      throw err;
+    } finally {
+      // Close the subsegment you created (### MySubSegment)
+      subsegment.close();
+      // Set back the original segment as active (## index.handler)
+      tracer.setSegment(handlerSegment);
+      // The main segment (facade) will be closed for you at the end by the decorator/middleware
     }
-
-    // Close subsegment
-    subsegment.close();
+    
+    return res;
   }
 }
 
-export const handlerClass = new MyFunctionWithDecorator();
-export const handler = handlerClass.handler;
+export const myFunction = new MyFunctionWithDecorator();
+export const handler = myFunction.handler;

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

@@ -1,43 +1,73 @@
 import middy from '@middy/core';
-import { Callback, Context } from 'aws-lambda';
-import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
+import { Context } from 'aws-lambda';
+import { Events } from '@aws-lambda-powertools/commons';
+import { Metrics, MetricUnits, logMetrics } from '@aws-lambda-powertools/metrics';
+import { Tracer, captureLambdaHandler } from '@aws-lambda-powertools/tracer';
+import { Logger, injectLambdaContext } from '@aws-lambda-powertools/logger';
 
-const metrics = new Metrics({ namespace: 'CDKExample', serviceName: 'withMiddy' }); // Sets metric namespace, and service as a metric dimension
+const namespace = 'CDKExample';
+const serviceName = 'MyFunctionWithMiddyMiddleware';
 
-type CustomEvent = {
-  throw: boolean
-};
+const metrics = new Metrics({ namespace: namespace, serviceName: serviceName });
+const logger = new Logger({ logLevel: 'INFO', serviceName: serviceName });
+const tracer = new Tracer({ serviceName: serviceName });
 
-class MyFunctionWithDecorator {
+const lambdaHandler = async (event: typeof Events.Custom.CustomEvent, context: Context) => {
+  // ### Experiment with Logger
+  // AWS Lambda context is automatically injected by the middleware
 
-  @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');
-    }
-  }
-}
+  logger.addPersistentLogAttributes({
+    testKey: 'testValue',
+  });
+  logger.debug('This is an DEBUG log'); // Won't show because we pass logLevel: 'INFO' in the constructor.
+  logger.info('This is an INFO log');
+  logger.warn('This is an WARN log');
+  logger.error('This is an ERROR log');
 
-const handler = middy(async (_event, _context) => {
+  // ### Experiment with Metrics
+  // Default metrics, cold start, and throwOnEmptyMetrics are enabled by the middleware
 
-  const handlerClass = new MyFunctionWithDecorator();
+  metrics.addMetric('test-metric', MetricUnits.Count, 10);
 
-  return handlerClass.handler(_event, _context, () => console.log('Lambda invoked!'));
-});
+  const metricWithItsOwnDimensions = metrics.singleMetric();
+  metricWithItsOwnDimensions.addDimension('InnerDimension', 'true');
+  metricWithItsOwnDimensions.addMetric('single-metric', MetricUnits.Percent, 50);
+  
+  // ### Experiment with Tracer
 
-handler.before(async (_request) => {
-  metrics.addMetric('beforeHandlerCalled', MetricUnits.Count, 1);
-});
+  // Service & Cold Start annotations will be added for you by the decorator/middleware
 
-handler.after(async (_request) => {
-  // Won't be flushed since happens after 
-  metrics.addMetric('afterHandlerCalled', MetricUnits.Count, 1);
+  // These traces will be added to the main segment (## index.handler)
+  tracer.putAnnotation('awsRequestId', context.awsRequestId);
+  tracer.putMetadata('eventPayload', event);
 
-});
+  // Create another subsegment & set it as active
+  const handlerSegment = tracer.getSegment(); // This is the custom segment created by Tracer for you (## index.handler)
+  const subsegment = handlerSegment.addNewSubsegment('### MySubSegment');
+  tracer.setSegment(subsegment);
 
-handler.onError(async (_request) => {
-  metrics.addMetric('onErrorHandlerCalled', MetricUnits.Count, 1);
-});
+  let res;
+  try {
+    res = { foo: 'bar' };
+  } catch (err) {
+    throw err;
+  } finally {
+    // Close the subsegment you created (### MySubSegment)
+    subsegment.close();
+    // Set back the original segment as active (## index.handler)
+    tracer.setSegment(handlerSegment);
+    // The main segment (facade) will be closed for you at the end by the decorator/middleware
+  }
+  
+  return res;
+}
 
-module.exports = { handler };
+// We instrument the handler with the various Middy middlewares
+export const handler = middy(lambdaHandler)
+  .use(captureLambdaHandler(tracer))
+  .use(logMetrics(metrics, {
+    captureColdStartMetric: true,
+    throwOnEmptyMetrics: true,
+    defaultDimensions: { environment: 'example', type: 'withDecorator' },
+  }))
+  .use(injectLambdaContext(logger));

examples/cdk/lib/example-function.Tracer.CaptureErrorDisabled.ts

@@ -3,11 +3,11 @@ import { Context } from 'aws-lambda';
 import { Events } from '@aws-lambda-powertools/commons';
 import { captureLambdaHandler, Tracer } from '@aws-lambda-powertools/tracer';
 
-// Set environment variable to disable capture response
+// Set environment variable to disable capture response - https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html
 process.env.POWERTOOLS_TRACER_ERROR_RESPONSE = 'false';
 const tracer = new Tracer({ serviceName: 'tracerCaptureErrorDisabledFn' });
 
-// In this example we are using the middleware pattern but you could use also the captureLambdaHandler decorator
+// In this example we are using the Middy middleware pattern but you can instrument your functions also with the captureLambdaHandler decorator & manual instrumentation
 export const handler = middy(async (event: typeof Events.Custom.CustomEvent, context: Context) => {
   tracer.putAnnotation('awsRequestId', context.awsRequestId);
   tracer.putMetadata('eventPayload', event);

examples/cdk/lib/example-function.Tracer.CaptureResponseDisabled.ts

@@ -3,7 +3,7 @@ import { Context } from 'aws-lambda';
 import { Events } from '@aws-lambda-powertools/commons';
 import { captureLambdaHandler, Tracer } from '@aws-lambda-powertools/tracer';
 
-// Set environment variable to disable capture response
+// Set environment variable to disable capture response - https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html
 process.env.POWERTOOLS_TRACER_CAPTURE_RESPONSE = 'false';
 const tracer = new Tracer({ serviceName: 'tracerCaptureResponseDisabledFn' });
 

examples/cdk/lib/example-function.Tracer.Decorator.ts

@@ -2,8 +2,9 @@ import { Callback, Context } from 'aws-lambda';
 import { Events } from '@aws-lambda-powertools/commons';
 import { Tracer } from '@aws-lambda-powertools/tracer';
 
-// process.env.POWERTOOLS_SERVICE_NAME = 'tracerManualFn'; // Alternative to setting the service name in the constructor
 const tracer = new Tracer({ serviceName: 'tracerDecoratorFn' });
+// Alternatively, you can also set the service name using the POWERTOOLS_SERVICE_NAME environment variable
+// Learn more at: https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html
 
 export class MyFunctionWithDecorator {  
   // We instrument the handler with the decorator and the tracer will automatically create a subsegment and capture relevant annotations and metadata