Exposed addResponseAsMetadata

Author: dreamorosi

docs/core/tracer.md

@@ -92,7 +92,7 @@ You can quickly start by importing the `Tracer` class, initialize it outside the
         try {
             res = ...
             // Add the response as metadata 
-            tracer.putMetadata(`${context.functionName} response`, res);
+            tracer.addResponseAsMetadata(res, context.functionName);
         } catch (err) {
             // Add the error as metadata
             handlerSegment.addError(err as Error, false);

packages/tracing/README.md

@@ -77,7 +77,7 @@ export const handler = async (_event: any, context: any) => {
     try {
         res = ...
         // Add the response as metadata 
-        tracer.putMetadata(`${context.functionName} response`, res);
+        tracer.addResponseAsMetadata(res, context.functionName);
     } catch (err) {
         // Add the error as metadata
         handlerSegment.addError(err as Error, false);

packages/tracing/src/Tracer.ts

@@ -90,7 +90,7 @@ import { Segment, Subsegment } from 'aws-xray-sdk-core';
  *   try {
  *     res = ...
  *     // Add the response as metadata
- *     tracer.putMetadata(`${context.functionName} response`, res);
+ *     tracer.addResponseAsMetadata(res, context.functionName);
  *   } catch (err) {
  *     // Add the error as metadata
  *     handlerSegment.addError(err as Error, false);
@@ -125,6 +125,22 @@ class Tracer implements TracerInterface {
     this.provider = new ProviderService();
   }
 
+  /**
+    * Add an data to the current segment or subsegment as metadata.
+    *
+    * @see https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-annotations
+    *
+    * @param data - Data to serialize as metadata
+    * @param methodName - Name of the method that is being traced
+    */
+  public addResponseAsMetadata(data?: unknown, methodName?: string): void {
+    if (data === undefined || this.captureResponse === false || this.tracingEnabled === false) {
+      return;
+    }
+
+    this.putMetadata(`${methodName} response`, data);
+  }
+
   /**
    * Patch all AWS SDK v2 clients and create traces when your application makes calls to AWS services.
    * 
@@ -382,18 +398,6 @@ class Tracer implements TracerInterface {
     return this.captureError;
   }
 
-  /**
-   * Get the current value of the `captureResponse` property.
-   * 
-   * You can use this method during manual instrumentation to determine
-   * if tracer should be capturing function responses.
-   * 
-   * @returns captureResponse - `true` if responses should be captured, `false` otherwise. 
-   */
-  public isCaptureResponseEnabled(): boolean {
-    return this.captureResponse;
-  }
-
   /**
    * Retrieve the current value of `ColdStart`.
    * 
@@ -537,23 +541,6 @@ class Tracer implements TracerInterface {
 
     subsegment.addError(error, false);
   }
-
-  /**
-    * Add an data to the current segment or subsegment as metadata.
-    * Used internally by decoratorators and middlewares.
-    *
-    * @see https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-errors
-    *
-    * @param data - Data to serialize as metadata
-    * @param methodName - Name of the method that is being traced
-    */
-  private addResponseAsMetadata(data?: unknown, methodName?: string): void {
-    if (data === undefined || this.captureResponse === false || this.tracingEnabled === false) {
-      return;
-    }
-
-    this.putMetadata(`${methodName} response`, data);
-  }
 
   /**
    * Add ColdStart annotation to the current segment or subsegment.

packages/tracing/src/middleware/middy.ts

@@ -41,11 +41,8 @@ const captureLambdaHandler = (target: Tracer): middy.MiddlewareObj => {
   const captureLambdaHandlerAfter = async (request: middy.Request): Promise<void> => {
     if (target.isTracingEnabled()) {
       const subsegment = target.getSegment();
-      if (request.response !== undefined && target.isCaptureResponseEnabled() === true) {
-        target.putMetadata(`${request.context.functionName} response`, request.response);
-      }
-      
-      subsegment?.close();
+      target.addResponseAsMetadata(request.response, request.context.functionName);
+      subsegment.close();
     }
   };
 

packages/tracing/tests/unit/Tracer.test.ts

@@ -24,6 +24,69 @@ describe('Class: Tracer', () => {
     process.env = ENVIRONMENT_VARIABLES;
   });
 
+  describe('Method: addResponseAsMetadata', () => {
+
+    test('when called while tracing is disabled, it does nothing', () => {
+
+      // Prepare
+      const tracer: Tracer = new Tracer({ enabled: false });
+      const putMetadataSpy = jest.spyOn(tracer, 'putMetadata');
+
+      // Act
+      tracer.addResponseAsMetadata({ foo: 'bar' }, context.functionName);
+
+      // Assess
+      expect(putMetadataSpy).toBeCalledTimes(0);
+
+    });
+
+    test('when called while POWERTOOLS_TRACER_CAPTURE_RESPONSE is set to false, it does nothing', () => {
+
+      // Prepare
+      process.env.POWERTOOLS_TRACER_CAPTURE_RESPONSE = 'false';
+      const tracer: Tracer = new Tracer();
+      const putMetadataSpy = jest.spyOn(tracer, 'putMetadata');
+
+      // Act
+      tracer.addResponseAsMetadata({ foo: 'bar' }, context.functionName);
+
+      // Assess
+      expect(putMetadataSpy).toBeCalledTimes(0);
+      delete process.env.POWERTOOLS_TRACER_CAPTURE_RESPONSE;
+
+    });
+
+    test('when called with data equal to undefined, it does nothing', () => {
+
+      // Prepare
+      const tracer: Tracer = new Tracer();
+      const putMetadataSpy = jest.spyOn(tracer, 'putMetadata');
+
+      // Act
+      tracer.addResponseAsMetadata(undefined, context.functionName);
+
+      // Assess
+      expect(putMetadataSpy).toBeCalledTimes(0);
+
+    });
+
+    test('when called with default config, it calls tracer.putMetadata correctly', () => {
+
+      // Prepare
+      const tracer: Tracer = new Tracer();
+      const putMetadataSpy = jest.spyOn(tracer, 'putMetadata').mockImplementation(() => null);
+
+      // Act
+      tracer.addResponseAsMetadata({ foo: 'bar' }, context.functionName);
+
+      // Assess
+      expect(putMetadataSpy).toBeCalledTimes(1);
+      expect(putMetadataSpy).toBeCalledWith(`${context.functionName} response`, expect.objectContaining({ foo: 'bar' }));
+
+    });
+
+  });
+
   describe('Method: isColdStart', () => {
 
     test('when called, it returns false the first time and always true after that', () => {