Exposed annotateColdStarted

Author: dreamorosi

docs/core/tracer.md

@@ -85,8 +85,7 @@ You can quickly start by importing the `Tracer` class, initialize it outside the
         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}`);
-        // TODO: expose tracer.annotateColdStart()
-        this.putAnnotation('ColdStart', tracer.isColdStart());
+        tracer.annotateColdStart()
 
         let res;
         try {

packages/tracing/README.md

@@ -70,8 +70,7 @@ 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}`);
-    // TODO: expose tracer.annotateColdStart()
-    this.putAnnotation('ColdStart', tracer.isColdStart());
+    tracer.annotateColdStart()
 
     let res;
     try {

packages/tracing/src/Tracer.ts

@@ -83,8 +83,7 @@ import { Segment, Subsegment } from 'aws-xray-sdk-core';
  *   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}`);
- *   // TODO: expose tracer.annotateColdStart()
- *   this.putAnnotation('ColdStart', tracer.isColdStart());
+ *   tracer.annotateColdStart()
  * 
  *   let res;
  *   try {
@@ -104,6 +103,7 @@ import { Segment, Subsegment } from 'aws-xray-sdk-core';
   * ```
  */
 class Tracer implements TracerInterface {
+  
   public static coldStart: boolean = true;
 
   public provider: ProviderServiceInterface;
@@ -163,6 +163,25 @@ class Tracer implements TracerInterface {
     this.putMetadata(`${methodName} response`, data);
   }
 
+  /**
+   * Add ColdStart annotation to the current segment or subsegment.
+   * 
+   * If Tracer has been initialized outside of the Lambda handler then the same instance
+   * of Tracer will be reused throghout the lifecycle of that same Lambda execution environment
+   * and this method will return `false` after the first invocation.
+   * 
+   * @see https://docs.aws.amazon.com/lambda/latest/dg/runtimes-context.html
+   */
+  public annotateColdStart(): void {
+    if (Tracer.coldStart === true) {
+      Tracer.coldStart = false;
+
+      if (this.tracingEnabled === true) {
+        this.putAnnotation('ColdStart', true);
+      }
+    }
+  }
+
   /**
    * Patch all AWS SDK v2 clients and create traces when your application makes calls to AWS services.
    * 
@@ -376,6 +395,27 @@ class Tracer implements TracerInterface {
       return descriptor;
     };
   }
+
+  /**
+   * Retrieve the current value of `ColdStart`.
+   * 
+   * If Tracer has been initialized outside of the Lambda handler then the same instance
+   * of Tracer will be reused throghout the lifecycle of that same Lambda execution environment
+   * and this method will return `false` after the first invocation.
+   * 
+   * @see https://docs.aws.amazon.com/lambda/latest/dg/runtimes-context.html
+   * 
+   * @returns boolean - `true` if is cold start, otherwise `false`
+   */
+  public static getColdStart(): boolean {
+    if (Tracer.coldStart === true) {
+      Tracer.coldStart = false;
+
+      return true;
+    }
+
+    return false;
+  }
 
   /**
    * Get the active segment or subsegment in the current scope.
@@ -408,27 +448,6 @@ class Tracer implements TracerInterface {
     return segment;
   }
 
-  /**
-   * Retrieve the current value of `ColdStart`.
-   * 
-   * If Tracer has been initialized outside of the Lambda handler then the same instance
-   * of Tracer will be reused throghout the lifecycle of that same Lambda execution environment
-   * and this method will return `false` after the first invocation.
-   * 
-   * @see https://docs.aws.amazon.com/lambda/latest/dg/runtimes-context.html
-   * 
-   * @returns boolean - `true` if is cold start, otherwise `false`
-   */
-  public static isColdStart(): boolean {
-    if (Tracer.coldStart === true) {
-      Tracer.coldStart = false;
-
-      return true;
-    }
-
-    return false;
-  }
-
   /**
    * Get the current value of the `tracingEnabled` property.
    * 
@@ -532,16 +551,6 @@ class Tracer implements TracerInterface {
   public setSegment(segment: Segment | Subsegment): void {
     return this.provider.setSegment(segment);
   }
-  
-  /**
-   * Add ColdStart annotation to the current segment or subsegment.
-   * Used internally by decoratorators and middlewares.
-   */
-  private annotateColdStart(): void {
-    if (Tracer.isColdStart()) {
-      this.putAnnotation('ColdStart', true);
-    }
-  }
 
   /**
    * Getter for `customConfigService`.

packages/tracing/src/middleware/middy.ts

@@ -31,10 +31,7 @@ const captureLambdaHandler = (target: Tracer): middy.MiddlewareObj => {
     if (target.isTracingEnabled()) {
       const subsegment = new Subsegment(`## ${request.context.functionName}`);
       target.setSegment(subsegment);
-  
-      if (Tracer.isColdStart()) {
-        target.putAnnotation('ColdStart', true);
-      }
+      target.annotateColdStart();
     }
   };
 

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

@@ -24,6 +24,42 @@ describe('Class: Tracer', () => {
     process.env = ENVIRONMENT_VARIABLES;
   });
 
+  describe('Method: annotateColdStart', () => {
+
+    test('when called while tracing is disabled, it does nothing', () => {
+
+      // Prepare
+      const tracer: Tracer = new Tracer({ enabled: false });
+      const putAnnotationSpy = jest.spyOn(tracer, 'putAnnotation');
+
+      // Act
+      tracer.annotateColdStart();
+
+      // Assess
+      expect(putAnnotationSpy).toBeCalledTimes(0);
+
+    });
+
+    test('when called multiple times, it annotates the first time and then never again', () => {
+
+      // Prepare
+      const tracer: Tracer = new Tracer();
+      const putAnnotationSpy = jest.spyOn(tracer, 'putAnnotation').mockImplementation(() => null);
+
+      // Act
+      tracer.annotateColdStart();
+      tracer.annotateColdStart();
+      tracer.annotateColdStart();
+      tracer.annotateColdStart();
+
+      // Assess
+      expect(putAnnotationSpy).toBeCalledTimes(1);
+      expect(putAnnotationSpy).toBeCalledWith('ColdStart', true);
+
+    });
+
+  });
+
   describe('Method: addResponseAsMetadata', () => {
 
     test('when called while tracing is disabled, it does nothing', () => {
@@ -144,15 +180,15 @@ describe('Class: Tracer', () => {
 
   });
 
-  describe('Method: isColdStart', () => {
+  describe('Method: getColdStart', () => {
 
     test('when called, it returns false the first time and always true after that', () => {
 
       // Assess
-      expect(Tracer.isColdStart()).toBe(true);
-      expect(Tracer.isColdStart()).toBe(false);
-      expect(Tracer.isColdStart()).toBe(false);
-      expect(Tracer.isColdStart()).toBe(false);
+      expect(Tracer.getColdStart()).toBe(true);
+      expect(Tracer.getColdStart()).toBe(false);
+      expect(Tracer.getColdStart()).toBe(false);
+      expect(Tracer.getColdStart()).toBe(false);
 
     });