chore(tracer): cdk examples + e2e tests (#347)

* Simplified base CDK examples

* Added Tracer examples

* Added back LambdaInterface in Tracer.test

* Updated package.json

* Updates to examples & docs

* Updated docs example

* Updated examples + added unit test groups

* Added base e2e tests

* Added back folder to jest config

* Added disabled tracer e2e test

* Added patch AWS SDK clients to manual e2e test

* Reduced test timeouts

* Added captureAWS feature to e2e

* Added additional e2e test cases

* Removed redundant e2e test files

* Relaxed dependency version on cdk examples

Author: dreamorosi

docs/core/tracer.md

@@ -93,7 +93,7 @@ You can quickly start by importing the `Tracer` class, initialize it outside the
     // OR tracer = Tracer({ service: 'example' });
 
     class Lambda {
-        @tracer.captureLambdaHanlder()
+        @tracer.captureLambdaHandler()
         public handler(event: any, context: any) {
             ...
         }
@@ -109,28 +109,34 @@ You can quickly start by importing the `Tracer` class, initialize it outside the
     import { Tracer } from '@aws-lambda-powertools/tracer';
 
     const tracer = Tracer(); // Sets service via env var
-    // OR tracer = Tracer({ service: 'example' });
+    // OR tracer = Tracer({ service: 'serverlessAirline' });
 
     export const handler = async (_event: any, context: any) => {
         const segment = tracer.getSegment(); // This is the facade segment (the one that is created by AWS Lambda)
-        // Create subsegment for the function
-        const handlerSegment = segment.addNewSubsegment(`## ${context.functionName}`);
+        // Create subsegment for the function & set it as active
+        const subsegment = segment.addNewSubsegment(`## ${process.env._HANDLER}`);
+        tracer.setSegment(subsegment);
+
+        // Annotate the subsegment with the cold start & serviceName
         tracer.annotateColdStart();
         tracer.addServiceNameAnnotation();
 
         let res;
         try {
             res = ...
             // Add the response as metadata 
-            tracer.addResponseAsMetadata(res, context.functionName);
+            tracer.addResponseAsMetadata(res, process.env._HANDLER);
         } catch (err) {
             // Add the error as metadata
             tracer.addErrorAsMetadata(err as Error);
+            throw err;
+        } finally {
+            // Close subsegment (the AWS Lambda one is closed automatically)
+            subsegment.close();
+            // Set the facade segment as active again
+            tracer.setSegment(segment);
         }
 
-        // Close subsegment (the AWS Lambda one is closed automatically)
-        handlerSegment.close();
-    
         return res;
     }
     ```
@@ -139,6 +145,7 @@ When using the `captureLambdaHandler` decorator or middleware, Tracer performs t
 
 * Handles the lifecycle of the subsegment
 * Creates a `ColdStart` annotation to easily filter traces that have had an initialization overhead
+* Creates a `ServiceName` annotation to easily filter traces that have a specific service name
 * Captures any response, or full exceptions generated by the handler, and include as tracing metadata
 
 ### Annotations & Metadata
@@ -153,10 +160,10 @@ When using the `captureLambdaHandler` decorator or middleware, Tracer performs t
     ```typescript hl_lines="6"
     import { Tracer } from '@aws-lambda-powertools/tracer';
 
-    const tracer = new Tracer({ serviceName: 'my-service' });
+    const tracer = new Tracer({ serviceName: 'serverlessAirline' });
 
     export const handler = async (_event: any, _context: any) => {
-        tracer.putAnnotation('PaymentStatus', "SUCCESS");
+        tracer.putAnnotation('successfulBooking', true);
     }
     ```
 === "Metadata"
@@ -165,11 +172,11 @@ When using the `captureLambdaHandler` decorator or middleware, Tracer performs t
     ```typescript hl_lines="7"
     import { Tracer } from '@aws-lambda-powertools/tracer';
 
-    const tracer = new Tracer({ serviceName: 'my-service' });
+    const tracer = new Tracer({ serviceName: 'serverlessAirline' });
 
     export const handler = async (_event: any, _context: any) => {
         const res = someLogic();
-        tracer.putMetadata('PaymentResponse', res);
+        tracer.putMetadata('paymentResponse', res);
     }
     ```
 
@@ -208,29 +215,32 @@ You can trace other methods using the `captureMethod` decorator or manual instru
 
 === "Manual"
 
-    ```typescript hl_lines="2 8-9 15 18 22"
+    ```typescript hl_lines="6 8-9 15 23 25"
     import { Tracer } from '@aws-lambda-powertools/tracer';
-    import { Segment } from 'aws-xray-sdk-core';
 
-    const tracer = new Tracer({ serviceName: 'my-service' });
+    const tracer = new Tracer({ serviceName: 'serverlessAirline' });
 
     const chargeId = async () => {
-        // Create subsegment & set it as active
-        const subsegment = new Subsegment(`### chargeId`);
+        const parentSubsegment = tracer.getSegment(); // This is the subsegment currently active
+        // Create subsegment for the function & set it as active
+        const subsegment = parentSubsegment.addNewSubsegment(`### chargeId`);
         tracer.setSegment(subsegment);
 
         let res;
         try {
             res = await someLogic(); // Do something
             // Add the response as metadata
-            tracer.putMetadata(`chargeId response`, data);
+            tracer.addResponseAsMetadata(res, 'chargeId');
         } catch (err) {
             // Add the error as metadata
-            subsegment.addError(err, false);
+            tracer.addErrorAsMetadata(err as Error);
+            throw err;
         }
 
-        // Close subsegment
+        // Close subsegment (the AWS Lambda one is closed automatically)
         subsegment.close();
+        // Set the facade segment as active again
+        tracer.setSegment(parentSubsegment);
 
         return res;
     }

docs/index.md

@@ -79,4 +79,4 @@ Each TypeScript utility is installed as standalone NPM package.
 ## Connect
 
 * **AWS Developers Slack**: `#lambda-powertools`** - **[Invite, if you don't have an account](https://join.slack.com/t/awsdevelopers/shared_invite/zt-yryddays-C9fkWrmguDv0h2EEDzCqvw){target="_blank"}**
-* **Email**: [email protected]
+* **Email**: [email protected]

examples/cdk/bin/cdk-app.ts

@@ -4,18 +4,4 @@ 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 */
-});
+new CdkAppStack(app, 'CdkAppStack', {});

examples/cdk/lib/example-stack.MyFunction.ts renamed to examples/cdk/lib/example-function.MyFunction.ts

@@ -10,7 +10,7 @@ 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> => {
+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)

examples/cdk/lib/example-stack.MyFunctionWithDecorator.ts renamed to examples/cdk/lib/example-function.MyFunctionWithDecorator.ts

@@ -1,4 +1,4 @@
-import middy from '@middy/core'
+import middy from '@middy/core';
 import { Callback, Context } from 'aws-lambda';
 import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
 

examples/cdk/lib/example-stack.MyFunctionWithMiddy.ts renamed to examples/cdk/lib/example-function.MyFunctionWithMiddy.ts

@@ -0,0 +1,27 @@
+import middy from '@middy/core';
+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
+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
+export const handler = middy(async (event: typeof Events.Custom.CustomEvent, context: Context) => {
+  tracer.putAnnotation('awsRequestId', context.awsRequestId);
+  tracer.putMetadata('eventPayload', event);
+
+  let res;
+  try {
+    res = { foo: 'bar' };
+    
+    // We are throwing an error only for testing purposes to make sure the error response is not captured in the subsegment metadata
+    throw new Error('An error occurred.');
+  } catch (err) {
+    // The error won't be in the subsegment metadata
+    throw err;
+  }
+  
+  return res;
+}).use(captureLambdaHandler(tracer));

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

@@ -0,0 +1,24 @@
+import middy from '@middy/core';
+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
+process.env.POWERTOOLS_TRACER_CAPTURE_RESPONSE = 'false';
+const tracer = new Tracer({ serviceName: 'tracerCaptureResponseDisabledFn' });
+
+// In this example we are using the middleware pattern but you could use also the captureLambdaHandler decorator
+export const handler = middy(async (event: typeof Events.Custom.CustomEvent, context: Context) => {
+  tracer.putAnnotation('awsRequestId', context.awsRequestId);
+  tracer.putMetadata('eventPayload', event);
+
+  let res;
+  try {
+    res = { foo: 'bar' };
+  } catch (err) {
+    throw err;
+  }
+  
+  // The response won't be captured in the subsegment metadata
+  return res;
+}).use(captureLambdaHandler(tracer));

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

@@ -0,0 +1,34 @@
+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' });
+
+export class MyFunctionWithDecorator {  
+  // We instrument the handler with the decorator and the tracer will automatically create a subsegment and capture relevant annotations and metadata
+  @tracer.captureLambdaHandler()
+  public handler(event: typeof Events.Custom.CustomEvent, context: Context, _callback: Callback<unknown>): void | Promise<unknown> {
+    // Add custom annotation & metadata
+    tracer.putAnnotation('awsRequestId', context.awsRequestId);
+    tracer.putMetadata('eventPayload', event);
+
+    let res: { foo: string };
+    try {
+      res = { foo: this.myMethod() };
+    } catch (err) {
+      throw err;
+    }
+
+    return new Promise((resolve, _reject) => resolve(res as unknown));
+  }
+
+  // We can also use decorators to create a subsegment for the method & capture response and errors as metadata
+  @tracer.captureMethod()
+  public myMethod(): string {
+    return 'bar';
+  }
+}
+
+export const handlerClass = new MyFunctionWithDecorator();
+export const handler = handlerClass.handler;

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

@@ -0,0 +1,23 @@
+import middy from '@middy/core';
+import { Context } from 'aws-lambda';
+import { Events } from '@aws-lambda-powertools/commons';
+import { captureLambdaHandler, Tracer } from '@aws-lambda-powertools/tracer';
+
+// process.env.POWERTOOLS_TRACE_ENABLED = 'false'; // Alternative to disabling tracing in the constructor
+const tracer = new Tracer({ serviceName: 'tracerDisabledFn', enabled: false });
+
+// In this example we are using the middleware pattern but you could use also the captureLambdaHandler decorator or the manual mode
+export const handler = middy(async (event: typeof Events.Custom.CustomEvent, context: Context) => {
+  // No tracing will be done and the commands will be ignored, this is useful for testing
+  tracer.putAnnotation('awsRequestId', context.awsRequestId);
+  tracer.putMetadata('eventPayload', event);
+
+  let res;
+  try {
+    res = { foo: 'bar' };
+  } catch (err) {
+    throw err;
+  }
+  
+  return res;
+}).use(captureLambdaHandler(tracer));

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

@@ -0,0 +1,39 @@
+import { 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: 'tracerManualFn' });
+
+export const handler = async (event: typeof Events.Custom.CustomEvent, context: Context): Promise<unknown> => {
+  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 subsegment = segment.addNewSubsegment(`## ${process.env._HANDLER}`);
+  tracer.setSegment(subsegment);
+
+  // Annotate the subsegment with the cold start & serviceName
+  tracer.annotateColdStart();
+  tracer.addServiceNameAnnotation();
+
+  // Add custom annotation & metadata
+  tracer.putAnnotation('awsRequestId', context.awsRequestId);
+  tracer.putMetadata('eventPayload', event);
+
+  let res;
+  try {
+    res = { foo: 'bar' };
+    // Add the response as metadata 
+    tracer.addResponseAsMetadata(res, process.env._HANDLER);
+  } catch (err) {
+    // Add the error as metadata
+    tracer.addErrorAsMetadata(err as Error);
+    throw err;
+  } finally {
+    // Close subsegment (the AWS Lambda one is closed automatically)
+    subsegment.close();
+    // Set the facade segment as active again
+    tracer.setSegment(segment);
+  }
+
+  return res;
+};

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

@@ -0,0 +1,23 @@
+import middy from '@middy/core';
+import { Context } from 'aws-lambda';
+import { Events } from '@aws-lambda-powertools/commons';
+import { captureLambdaHandler, 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: 'tracerMiddlewareFn' });
+
+// We instrument the handler with the middy middleware and the tracer will automatically create a subsegment and capture relevant annotations and metadata
+export const handler = middy(async (event: typeof Events.Custom.CustomEvent, context: Context) => {
+  // Add custom annotation & metadata
+  tracer.putAnnotation('awsRequestId', context.awsRequestId);
+  tracer.putMetadata('eventPayload', event);
+
+  let res;
+  try {
+    res = { foo: 'bar' };
+  } catch (err) {
+    throw err;
+  }
+  
+  return res;
+}).use(captureLambdaHandler(tracer));

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

@@ -0,0 +1,33 @@
+import { Context } from 'aws-lambda';
+import { Events } from '@aws-lambda-powertools/commons';
+import { Tracer } from '@aws-lambda-powertools/tracer';
+import { STS } from 'aws-sdk';
+
+// process.env.POWERTOOLS_SERVICE_NAME = 'tracerManualFn'; // Alternative to setting the service name in the constructor
+const tracer = new Tracer({ serviceName: 'tracerPatchAWSSDKv2Fn' });
+// To patch a specific AWS SDK Client, we pass it to the Tracer that will return an instrumented version of it
+const sts = tracer.captureAWSClient(new STS());
+
+export const handler = async (_event: typeof Events.Custom.CustomEvent, _context: Context): Promise<unknown> => {
+  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 subsegment = segment.addNewSubsegment(`## ${process.env._HANDLER}`);
+  tracer.setSegment(subsegment);
+  
+  let res;
+  try {
+    // Tracer will create a subsegment for the AWS SDK call and capture relevant annotations and metadata
+    res = await sts.getCallerIdentity({}).promise();
+    // Add custom metadata with the response object
+    tracer.putMetadata('awsResponse', res);
+  } catch (err) {
+    throw err;
+  }
+
+  // Close subsegment (the AWS Lambda one is closed automatically)
+  subsegment.close();
+  // Set the facade segment as active again
+  tracer.setSegment(segment);
+
+  return res;
+};