feat: add tracer

packages/tracing/README.md

@@ -0,0 +1,21 @@
+# `tracer`
+
+## Usage
+
+```bash
+
+npm run test
+
+npm run example:hello-world
+npm run example:capture-lambda-handler-response-decorator
+npm run example:capture-lambda-handler-error-decorator
+
+```
+
+### Getting started
+
+```typescript
+// Import the library
+import { Tracer } from "../src";
+// When going public, it will be something like: import { Tracer } from '@aws-lambda-powertools/tracer';
+```

packages/tracing/examples/capture-clients.ts

@@ -0,0 +1,53 @@
+// Populate runtime
+require('./../tests/helpers/populateEnvironmentVariables');
+
+// Additional runtime variables
+process.env.POWERTOOLS_SERVICE_NAME = 'hello-world';
+process.env.AWS_XRAY_DEBUG_MODE = 'TRUE';
+
+import * as dummyEvent from '../../../tests/resources/events/custom/hello-world.json';
+import { context as dummyContext } from '../../../tests/resources/contexts/hello-world';
+import { TracingNamespace as dummyTracingNamespace } from './utils/namespaces/hello-world';
+import { Handler } from 'aws-lambda';
+import { Tracer } from '../src';
+
+const tracer = new Tracer();
+
+class DummyServiceV2 {
+  private customRequestHandler?: null | unknown;
+
+  public act(): void {
+    return;
+  }
+
+  public customizeRequests(callback: unknown): void {
+    if (!callback) {
+      this.customRequestHandler = null;
+    } else if (typeof callback === 'function') {
+      this.customRequestHandler = callback;
+    } else {
+      throw new Error('Invalid callback type \'' + typeof callback + '\' provided in customizeRequests');
+    }
+  }
+}
+
+class DummyServiceV3 {
+  private customRequestHandler?: null | unknown;
+
+  public act(): void {
+    return;
+  }
+
+}
+
+const lambdaHandler: Handler = async () => {
+  const dummyServiceV2 = tracer.captureAWSClient(new DummyServiceV2());
+  dummyServiceV2?.act();
+
+  const dummyServiceV3 = tracer.captureAWSv3Client(new DummyServiceV3());
+  dummyServiceV3?.act();
+};
+
+dummyTracingNamespace(tracer, () => {
+  lambdaHandler(dummyEvent, dummyContext, () => console.log('Lambda invoked!'));
+});

packages/tracing/examples/capture-lambda-handler-error-decorator.ts

@@ -0,0 +1,31 @@
+// Populate runtime
+require('./../tests/helpers/populateEnvironmentVariables');
+
+// Additional runtime variables
+process.env.POWERTOOLS_SERVICE_NAME = 'hello-world';
+process.env.AWS_XRAY_DEBUG_MODE = 'TRUE';
+
+import * as dummyEvent from '../../../tests/resources/events/custom/hello-world.json';
+import { context as dummyContext } from '../../../tests/resources/contexts/hello-world';
+import { TracingNamespace as dummyTracingNamespace } from './utils/namespaces/hello-world';
+import { LambdaInterface } from './utils/lambda/LambdaInterface';
+import { Tracer } from '../src';
+import { Callback, Context } from 'aws-lambda/handler';
+
+const tracer = new Tracer();
+
+class Lambda implements LambdaInterface {
+
+  @tracer.captureLambdaHanlder()
+  public handler<TEvent, TResult>(_event: TEvent, _context: Context, _callback: Callback<TResult>): void | Promise<TResult> {
+
+    tracer.putAnnotation('StringAnnotation', 'AnnotationValue');
+
+    throw new Error('foo bar');
+  }
+
+}
+
+dummyTracingNamespace(tracer, () => {
+  new Lambda().handler(dummyEvent, dummyContext, () => console.log('Lambda invoked!'));
+});

packages/tracing/examples/capture-lambda-handler-response-decorator.ts

@@ -0,0 +1,33 @@
+// Populate runtime
+require('./../tests/helpers/populateEnvironmentVariables');
+
+// Additional runtime variables
+process.env.POWERTOOLS_SERVICE_NAME = 'hello-world';
+process.env.AWS_XRAY_DEBUG_MODE = 'TRUE';
+
+import * as dummyEvent from '../../../tests/resources/events/custom/hello-world.json';
+import { context as dummyContext } from '../../../tests/resources/contexts/hello-world';
+import { TracingNamespace as dummyTracingNamespace } from './utils/namespaces/hello-world';
+import { LambdaInterface } from './utils/lambda/LambdaInterface';
+import { Tracer } from '../src';
+import { Callback, Context } from 'aws-lambda/handler';
+
+const tracer = new Tracer();
+
+class Lambda implements LambdaInterface {
+
+  @tracer.captureLambdaHanlder()
+  public handler<TEvent, TResult>(_event: TEvent, _context: Context, _callback: Callback<TResult>): void | Promise<TResult> {
+
+    tracer.putAnnotation('StringAnnotation', 'AnnotationValue');
+
+    return new Promise((resolve, _reject) => resolve({
+      foo: 'bar'
+    } as unknown as TResult));
+  }
+
+}
+
+dummyTracingNamespace(tracer, () => {
+  new Lambda().handler(dummyEvent, dummyContext, () => console.log('Lambda invoked!'));
+});

packages/tracing/examples/hello-world.ts

@@ -0,0 +1,31 @@
+// Populate runtime
+require('./../tests/helpers/populateEnvironmentVariables');
+
+// Additional runtime variables
+process.env.POWERTOOLS_SERVICE_NAME = 'hello-world';
+process.env.AWS_XRAY_DEBUG_MODE = 'TRUE';
+
+import * as dummyEvent from '../../../tests/resources/events/custom/hello-world.json';
+import { context as dummyContext } from '../../../tests/resources/contexts/hello-world';
+import { TracingNamespace as dummyTracingNamespace } from './utils/namespaces/hello-world';
+import { Handler } from 'aws-lambda';
+import { Tracer } from '../src';
+
+const tracer = new Tracer();
+
+const lambdaHandler: Handler = async () => {
+  tracer.putAnnotation('StringAnnotation', 'AnnotationValue');
+  tracer.putAnnotation('NumberAnnotation', 1234);
+  tracer.putAnnotation('BooleanAnnotationKey', true);
+  tracer.putMetadata('MetadataKey', {});
+  tracer.putMetadata('MetadataKey', {}, 'SomeNameSpace');
+
+  return {
+    foo: 'bar'
+  };
+
+};
+
+dummyTracingNamespace(tracer, () => {
+  lambdaHandler(dummyEvent, dummyContext, () => console.log('Lambda invoked!'));
+});

packages/tracing/examples/utils/lambda/LambdaInterface.ts

@@ -0,0 +1,9 @@
+import { Handler } from 'aws-lambda';
+
+interface LambdaInterface {
+  handler: Handler
+}
+
+export {
+  LambdaInterface
+};

packages/tracing/examples/utils/lambda/index.ts

@@ -0,0 +1 @@
+export * from './LambdaInterface';

packages/tracing/examples/utils/namespaces/hello-world.ts

@@ -0,0 +1,16 @@
+import { Segment } from 'aws-xray-sdk-core';
+import { Tracer } from 'Tracer';
+
+const TracingNamespace = (tracer: Tracer, handler: () => void): void => {
+  const ns = tracer.provider.getNamespace();
+  ns.run(() => {
+    const segment = new Segment('facade', process.env._X_AMZN_TRACE_ID || null);
+    tracer.provider.setSegment(segment);
+    handler();
+    // segment.close();
+  });
+};
+
+export {
+  TracingNamespace
+};

packages/tracing/jest.config.js

@@ -0,0 +1,43 @@
+module.exports = {
+  displayName: {
+    name: 'AWS Lambda Powertools utility: TRACER',
+    color: 'cyan',
+  },
+  'preset': 'ts-jest',
+  'transform': {
+    '^.+\\.ts?$': 'ts-jest',
+  },
+  moduleFileExtensions: [ 'js', 'ts' ],
+  'collectCoverageFrom': [
+    '**/src/**/*.ts',
+    '!**/node_modules/**',
+  ],
+  'testMatch': ['**/?(*.)+(spec|test).ts'],
+  'roots': [
+    '<rootDir>/src',
+    '<rootDir>/tests',
+  ],
+  'testPathIgnorePatterns': [
+    '/node_modules/',
+  ],
+  'testEnvironment': 'node',
+  'coveragePathIgnorePatterns': [
+    '/node_modules/',
+  ],
+  'coverageThreshold': {
+    'global': {
+      'statements': 100,
+      'branches': 100,
+      'functions': 100,
+      'lines': 100,
+    },
+  },
+  'coverageReporters': [
+    'json-summary',
+    'text',
+    'lcov'
+  ],
+  'setupFiles': [
+    '<rootDir>/tests/helpers/populateEnvironmentVariables.ts'
+  ]
+};