Feature parity w/ Python #861

Author: dreamorosi

docs/core/tracer.md

@@ -9,7 +9,7 @@ Tracer is an opinionated thin wrapper for [AWS X-Ray SDK for Node.js](https://gi
 
 ## Key features
 
-* Auto capture cold start as annotation, and responses or full exceptions as metadata
+* Auto capture cold start and service name as annotations, and responses or full exceptions as metadata
 * Auto-disable when not running in AWS Lambda environment
 * Support tracing functions via decorators, middleware, and manual instrumentation
 * Support tracing AWS SDK v2 and v3 via AWS X-Ray SDK for Node.js
@@ -85,7 +85,8 @@ 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}`);
-        tracer.annotateColdStart()
+        tracer.annotateColdStart();
+        tracer.addServiceNameAnnotation();
 
         let res;
         try {

packages/tracing/README.md

@@ -5,7 +5,7 @@ Tracer is an opinionated thin wrapper for [AWS X-Ray SDK for Node.js](https://gi
 Tracing data can be visualized through AWS X-Ray Console.
 
 ## Key features
-* Auto capture cold start as annotation, and responses or full exceptions as metadata
+* Auto capture cold start and service name as annotations, and responses or full exceptions as metadata
 * Auto-disable when not running in AWS Lambda environment
 * Support tracing functions via decorators, middleware, and manual instrumentation
 * Support tracing AWS SDK v2 and v3 via AWS X-Ray SDK for Node.js
@@ -18,7 +18,7 @@ For more usage examples, see [our documentation](https://awslabs.github.io/aws-l
 
 If you use function-based Lambda handlers you can use the [captureLambdaHanlder()](./_aws_lambda_powertools_tracer.Tracer.html) middy middleware to automatically:
 * handle the subsegment lifecycle 
-* add the `ColdStart` annotation
+* add the `ServiceName` and `ColdStart` annotations
 * add the function response as metadata
 * add the function error as metadata (if any)
 
@@ -37,7 +37,7 @@ export const handler = middy(async (_event: any, _context: any) => {
 
 If instead you use TypeScript Classes to wrap your Lambda handler you can use the [@tracer.captureLambdaHanlder()](./_aws_lambda_powertools_tracer.Tracer.html#captureLambdaHanlder) decorator to automatically:
 * handle the subsegment lifecycle 
-* add the `ColdStart` annotation
+* add the `ServiceName` and `ColdStart` annotations
 * add the function response as metadata
 * add the function error as metadata (if any)
 
@@ -70,7 +70,8 @@ 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}`);
-    tracer.annotateColdStart()
+    tracer.annotateColdStart();
+    tracer.addServiceNameAnnotation();
 
     let res;
     try {

packages/tracing/src/Tracer.ts

@@ -25,7 +25,7 @@ import { Segment, Subsegment } from 'aws-xray-sdk-core';
  * 
  * If you use function-based Lambda handlers you can use the [captureLambdaHanlder()](./_aws_lambda_powertools_tracer.Tracer.html) middy middleware to automatically:
  * * handle the subsegment lifecycle 
- * * add the `ColdStart` annotation
+ * * add the `ServiceName` and `ColdStart` annotations
  * * add the function response as metadata
  * * add the function error as metadata (if any)
  * 
@@ -45,7 +45,7 @@ import { Segment, Subsegment } from 'aws-xray-sdk-core';
  * 
  * If instead you use TypeScript Classes to wrap your Lambda handler you can use the [@tracer.captureLambdaHanlder()](./_aws_lambda_powertools_tracer.Tracer.html#captureLambdaHanlder) decorator to automatically:
  * * handle the subsegment lifecycle 
- * * add the `ColdStart` annotation
+ * * add the `ServiceName` and `ColdStart` annotations
  * * add the function response as metadata
  * * add the function error as metadata (if any)
  * 
@@ -84,6 +84,7 @@ import { Segment, Subsegment } from 'aws-xray-sdk-core';
  *   // Create subsegment for the function
  *   const handlerSegment = segment.addNewSubsegment(`## ${context.functionName}`);
  *   tracer.annotateColdStart()
+ *   tracer.addServiceNameAnnotation();
  * 
  *   let res;
  *   try {
@@ -116,7 +117,7 @@ class Tracer implements TracerInterface {
 
   private envVarsService?: EnvironmentVariablesService;
 
-  private serviceName: string = 'serviceUndefined';
+  private serviceName?: string;
 
   private tracingEnabled: boolean = true;
 
@@ -148,7 +149,7 @@ class Tracer implements TracerInterface {
   }
 
   /**
-    * Add an data to the current segment or subsegment as metadata.
+    * Add response data to the current segment or subsegment as metadata.
     *
     * @see https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-annotations
     *
@@ -163,6 +164,17 @@ class Tracer implements TracerInterface {
     this.putMetadata(`${methodName} response`, data);
   }
 
+  /**
+   * Add service name to the current segment or subsegment as annotation.
+   * 
+   */
+  public addServiceNameAnnotation(): void {
+    if (this.tracingEnabled === false || this.serviceName === undefined) {
+      return;
+    }
+    this.putAnnotation('Service', this.serviceName);
+  }
+
   /**
    * Add ColdStart annotation to the current segment or subsegment.
    * 
@@ -311,6 +323,7 @@ class Tracer implements TracerInterface {
 
         return this.provider.captureAsyncFunc(`## ${context.functionName}`, async subsegment => {
           this.annotateColdStart();
+          this.addServiceNameAnnotation();
           let result: unknown;
           try {
             result = await originalMethod?.apply(target, [ event, context, callback ]);

packages/tracing/src/middleware/middy.ts

@@ -32,6 +32,7 @@ const captureLambdaHandler = (target: Tracer): middy.MiddlewareObj => {
       const subsegment = new Subsegment(`## ${request.context.functionName}`);
       target.setSegment(subsegment);
       target.annotateColdStart();
+      target.addServiceNameAnnotation();
     }
   };
 

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

@@ -65,6 +65,54 @@ describe('Class: Tracer', () => {
 
   });
 
+  describe('Method: addServiceNameAnnotation', () => {
+
+    test('when called while tracing is disabled, it does nothing', () => {
+
+      // Prepare
+      const tracer: Tracer = new Tracer({ enabled: false });
+      const putAnnotation = jest.spyOn(tracer, 'putAnnotation');
+
+      // Act
+      tracer.addServiceNameAnnotation();
+
+      // Assess
+      expect(putAnnotation).toBeCalledTimes(0);
+
+    });
+
+    test('when called while a serviceName has been set, it adds it as annotation', () => {
+
+      // Prepare
+      const tracer: Tracer = new Tracer({ serviceName: 'foo' });
+      const putAnnotation = jest.spyOn(tracer, 'putAnnotation').mockImplementation(() => null);
+
+      // Act
+      tracer.addServiceNameAnnotation();
+
+      // Assess
+      expect(putAnnotation).toBeCalledTimes(1);
+      expect(putAnnotation).toBeCalledWith('Service', 'foo');
+
+    });
+
+    test('when called while a serviceName has not been set, it does nothing', () => {
+
+      // Prepare
+      delete process.env.POWERTOOLS_SERVICE_NAME;
+      const tracer: Tracer = new Tracer();
+      const putAnnotation = jest.spyOn(tracer, 'putAnnotation').mockImplementation(() => null);
+
+      // Act
+      tracer.addServiceNameAnnotation();
+
+      // Assess
+      expect(putAnnotation).toBeCalledTimes(0);
+
+    });
+
+  });
+
   describe('Method: addResponseAsMetadata', () => {
 
     test('when called while tracing is disabled, it does nothing', () => {
@@ -692,22 +740,60 @@ describe('Class: Tracer', () => {
       // Assess
       expect(captureAsyncFuncSpy).toHaveBeenCalledTimes(2);
       expect(captureAsyncFuncSpy).toHaveBeenCalledWith('## foo-bar-function', expect.anything());
-      expect(putAnnotationSpy).toHaveBeenCalledTimes(2);
-      expect(putAnnotationSpy.mock.calls).toEqual([
+      expect(putAnnotationSpy.mock.calls.filter(call => 
+        call[0] === 'ColdStart'
+      )).toEqual([
         [ 'ColdStart', true ],
         [ 'ColdStart', false ],
       ]);
       expect(newSubsegmentFirstInvocation).toEqual(expect.objectContaining({
         name: '## foo-bar-function',
-        annotations: {
+        annotations: expect.objectContaining({
           'ColdStart': true,
-        }
+        })
       }));
       expect(newSubsegmentSecondInvocation).toEqual(expect.objectContaining({
         name: '## foo-bar-function',
-        annotations: {
+        annotations: expect.objectContaining({
           'ColdStart': false,
+        })
+      }));
+
+    });
+
+    test('when used as decorator and with standard config, it annotates Service correctly', async () => {
+      
+      // Prepare
+      const tracer: Tracer = new Tracer();
+      const newSubsegment: Segment | Subsegment | undefined = new Subsegment('## foo-bar-function');
+      jest.spyOn(tracer.provider, 'getSegment')
+        .mockImplementation(() => newSubsegment);
+      setContextMissingStrategy(() => null);
+      const captureAsyncFuncSpy = jest.spyOn(tracer.provider, 'captureAsyncFunc');
+      class Lambda implements LambdaInterface {
+
+        @tracer.captureLambdaHanlder()
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
+        public handler<TEvent, TResult>(_event: TEvent, _context: Context, _callback: Callback<TResult>): void | Promise<TResult> {
+          return new Promise((resolve, _reject) => resolve({
+            foo: 'bar'
+          } as unknown as TResult));
         }
+            
+      }
+            
+      // Act
+      await new Lambda().handler(event, context, () => console.log('Lambda invoked!'));
+
+      // Assess
+      expect(captureAsyncFuncSpy).toHaveBeenCalledTimes(1);
+      expect(captureAsyncFuncSpy).toHaveBeenCalledWith('## foo-bar-function', expect.anything());
+      expect(newSubsegment).toEqual(expect.objectContaining({
+        name: '## foo-bar-function',
+        annotations: expect.objectContaining({
+          'Service': 'hello-world',
+        })
       }));
 
     });

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

@@ -2,7 +2,7 @@ import { ConfigServiceInterface } from '../../src/config';
 import { TracerOptions } from '../../src/types';
 import { createTracer, Tracer } from './../../src';
 
-describe('Helper: createLogger function', () => {
+describe('Helper: createTracer function', () => {
   const ENVIRONMENT_VARIABLES = process.env;
 
   beforeEach(() => {
@@ -212,20 +212,6 @@ describe('Helper: createLogger function', () => {
 
     });
 
-    test('when POWERTOOLS_SERVICE_NAME environment variable is set to invalid value, a tracer default serviceName is returned', () => {
-      // Prepare
-      process.env.POWERTOOLS_SERVICE_NAME = '';
-
-      // Act
-      const tracer = createTracer();
-
-      // Assess
-      expect(tracer).toEqual(expect.objectContaining({
-        serviceName: 'serviceUndefined'
-      }));
-
-    });
-
     test('when POWERTOOLS_TRACER_CAPTURE_RESPONSE environment variable is set, a tracer with captureResponse disabled is returned', () => {
       // Prepare
       process.env.POWERTOOLS_TRACER_CAPTURE_RESPONSE = 'false';

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

@@ -232,22 +232,54 @@ describe('Middy middlewares', () => {
     expect(setSegmentSpy).toHaveBeenCalledWith(expect.objectContaining({
       name: '## foo-bar-function',
     }));
-    expect(putAnnotationSpy).toHaveBeenCalledTimes(2);
-    expect(putAnnotationSpy.mock.calls).toEqual([
+    expect(putAnnotationSpy.mock.calls.filter(call => 
+      call[0] === 'ColdStart'
+    )).toEqual([
       [ 'ColdStart', true ],
       [ 'ColdStart', false ],
     ]);
     expect(newSubsegmentFirstInvocation).toEqual(expect.objectContaining({
       name: '## foo-bar-function',
-      annotations: {
+      annotations: expect.objectContaining({
         'ColdStart': true,
-      }
+      })
     }));
     expect(newSubsegmentSecondInvocation).toEqual(expect.objectContaining({
       name: '## foo-bar-function',
-      annotations: {
+      annotations: expect.objectContaining({
         'ColdStart': false,
-      }
+      })
+    }));
+
+  });
+
+  test('when used with standard config, it annotates Service correctly', async () => {
+      
+    // Prepare
+    const tracer: Tracer = new Tracer();
+    const newSubsegment: Segment | Subsegment | undefined = new Subsegment('## foo-bar-function');
+    const setSegmentSpy = jest.spyOn(tracer.provider, 'setSegment').mockImplementation();
+    jest.spyOn(tracer.provider, 'getSegment').mockImplementation(() => newSubsegment);
+    setContextMissingStrategy(() => null);
+    const lambdaHandler: Handler = async (_event: unknown, _context: Context) => ({
+      foo: 'bar'
+    });
+    const handler = middy(lambdaHandler).use(captureLambdaHandler(tracer));
+    const context = Object.assign({}, mockContext);
+
+    // Act
+    await handler({}, context, () => console.log('Lambda invoked!'));
+
+    // Assess
+    expect(setSegmentSpy).toHaveBeenCalledTimes(1);
+    expect(setSegmentSpy).toHaveBeenCalledWith(expect.objectContaining({
+      name: '## foo-bar-function',
+    }));
+    expect(newSubsegment).toEqual(expect.objectContaining({
+      name: '## foo-bar-function',
+      annotations: expect.objectContaining({
+        'Service': 'hello-world',
+      })
     }));
 
   });