Documentation

Author: dreamorosi

docs/core/tracer.md

@@ -42,17 +42,16 @@ You can quickly start by importing the `Tracer` class, initialize it outside the
 
 === "Middleware"
 
-    ```typescript hl_lines="1 3 6"
+    ```typescript hl_lines="1-2 4 7 9"
     import { Tracer } from '@aws-lambda-powertools/tracer';
+    import middy from '@middy/core';
 
     const tracer = Tracer(); // Sets service via env var
     // OR tracer = Tracer({ service: 'example' });
 
-    // TODO: update example once middleware has been implemented.
-
-    export const handler = async (_event: any, _context: any) => {
+    export const handler = middy(async (_event: any, _context: any) => {
         ...
-    }
+    }).use(captureLambdaHandler(tracer));
     ```
 
 === "Decorator"
@@ -76,7 +75,7 @@ You can quickly start by importing the `Tracer` class, initialize it outside the
 
 === "Manual"
 
-    ```typescript hl_lines="1-2 4 8-9 11 17 20 24"
+    ```typescript hl_lines="1-2 4 9-10 12 18 21 25"
     import { Tracer } from '@aws-lambda-powertools/tracer';
     import { Segment } from 'aws-xray-sdk-core';
 
@@ -107,8 +106,7 @@ You can quickly start by importing the `Tracer` class, initialize it outside the
     }
     ```
 
-<!-- TODO: Replace name of middleware once implemented -->
-When using thes `captureLambdaHanlder` decorator or the `TBD` middleware, Tracer performs these additional tasks to ease operations:
+When using the `captureLambdaHanlder` decorator or middleware, Tracer performs these additional tasks to ease operations:
 
 * Handles the lifecycle of the subsegment
 * Creates a `ColdStart` annotation to easily filter traces that have had an initialization overhead
@@ -148,23 +146,10 @@ When using thes `captureLambdaHanlder` decorator or the `TBD` middleware, Tracer
 
 ### Methods
 
-You can trace other methods using the `captureMethod` decorator.
-
-=== "Middleware"
-
-    ```typescript hl_lines="1 3 6"
-    import { Tracer } from '@aws-lambda-powertools/tracer';
-
-    const tracer = Tracer();
+You can trace other methods using the `captureMethod` decorator or manual instrumentation.
 
-    // TODO: update example once middleware has been implemented.
-
-
-
-    export const handler = async (_event: any, _context: any) => {
-        ...
-    }
-    ```
+!!! info
+    We currently support a middleware for tracing methods, [let us know](https://github.com/awslabs/aws-lambda-powertools-typecsript/issues/new?assignees=&labels=feature-request%2C+triage&template=feature_request.md&title=) if you'd like to see one!
 
 === "Decorator"
 

packages/tracing/src/Tracer.ts

@@ -20,11 +20,28 @@ import { Segment, Subsegment } from 'aws-xray-sdk-core';
  * ## Usage
  * 
  * ### Functions usage with middlewares
- * TBD
+ * 
+ * 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 function response as metadata
+ * * add the function error as metadata (if any)
+ * 
+ * @example
+ * ```typescript
+ * import { Tracer, captureLambdaHandler } from '@aws-lambda-powertools/tracer';
+ * import middy from '@middy/core';
+ * 
+ * const tracer = new Tracer({ serviceName: 'my-service' });
+ * 
+ * export const handler = middy(async (_event: any, _context: any) => {
+ *   ...
+ * }).use(captureLambdaHandler(tracer));
+ * ```
  * 
  * ### Object oriented usage with decorators
  * 
- * If 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:
+ * 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 function response as metadata
@@ -65,7 +82,7 @@ import { Segment, Subsegment } from 'aws-xray-sdk-core';
  *   const subsegment = new Subsegment(`## ${context.functionName}`);
  *   tracer.setSegment(subsegment);
  *   // Add the ColdStart annotation
- *   this.putAnnotation('ColdStart', tracer.coldStart);
+ *   this.putAnnotation('ColdStart', tracer.isColdStart());
  * 
  *   let res;
  *   try {
@@ -351,10 +368,26 @@ class Tracer implements TracerInterface {
     return segment;
   }
 
+  /**
+   * Get the current value of the `captureError` property.
+   * 
+   * You can use this method during manual instrumentation to determine
+   * if tracer should be capturing errors.
+   * 
+   * @returns captureError - `true` if errors should be captured, `false` otherwise. 
+   */
   public isCaptureErrorEnabled(): boolean {
     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;
   }
@@ -368,7 +401,7 @@ class Tracer implements TracerInterface {
    * 
    * @see https://docs.aws.amazon.com/lambda/latest/dg/runtimes-context.html
    * 
-   * @returns boolean - true if is cold start otherwise false
+   * @returns boolean - `true` if is cold start, otherwise `false`
    */
   public static isColdStart(): boolean {
     if (Tracer.coldStart === true) {
@@ -380,6 +413,14 @@ class Tracer implements TracerInterface {
     return false;
   }
 
+  /**
+   * Get the current value of the `tracingEnabled` property.
+   * 
+   * You can use this method during manual instrumentation to determine
+   * if tracer is currently enabled.
+   * 
+   * @returns tracingEnabled - `true` if tracing is enabled, `false` otherwise. 
+   */
   public isTracingEnabled(): boolean {
     return this.tracingEnabled;
   }

packages/tracing/src/index.ts

@@ -1,3 +1,4 @@
 export * from './helpers';
 export * from './Tracer';
-export * from './TracerInterface';
+export * from './TracerInterface';
+export * from './middleware/middy';

packages/tracing/src/middleware/middy.ts

@@ -2,6 +2,30 @@ import middy from '@middy/core';
 import { Subsegment } from 'aws-xray-sdk-core';
 import { Tracer } from '../Tracer';
 
+/**
+ * A middy middleware automating capture of metadata and annotations on segments or subsegments ofr a Lambda Handler.
+ * 
+ * Using this middleware on your handler function will automatically:
+ * * handle the subsegment lifecycle 
+ * * add the `ColdStart` annotation
+ * * add the function response as metadata
+ * * add the function error as metadata (if any)
+ * 
+ * @example
+ * ```typescript
+ * import { Tracer, captureLambdaHandler } from '@aws-lambda-powertools/tracer';
+ * import middy from '@middy/core';
+ * 
+ * const tracer = new Tracer({ serviceName: 'my-service' });
+ * 
+ * export const handler = middy(async (_event: any, _context: any) => {
+ *   ...
+ * }).use(captureLambdaHandler(tracer));
+ * ```
+ * 
+ * @param tracer - The Tracer instance to use for tracing
+ * @returns middleware object - The middy middleware object
+ */
 const captureLambdaHandler = (target: Tracer): middy.MiddlewareObj => {
   const captureLambdaHandlerBefore = async (request: middy.Request): Promise<void> => {
     if (target.isTracingEnabled()) {
@@ -34,7 +58,9 @@ const captureLambdaHandler = (target: Tracer): middy.MiddlewareObj => {
         subsegment?.addError(request.error as Error, false);
       }
       // TODO: should this error be thrown?? I.e. should we stop the event flow & return?
-      // throw error;
+      // throw request.error;
+
+      subsegment?.close();
     }
   };