Updates to examples & docs

Author: dreamorosi

docs/core/tracer.md

@@ -16,6 +16,14 @@ Tracer is an opinionated thin wrapper for [AWS X-Ray SDK for Node.js](https://gi
 
 ## Getting started
 
+Tracer has three global settings that can be used to configure its behavior:
+
+Setting | Description | Environment variable | Constructor parameter
+------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------
+**Trace Enabled** | Explicitly enables/disables tracing | `POWERTOOLS_TRACE_ENABLED` | `enabled`
+**Capture Responses** | Captures Lambda or method return as metadata |  `POWERTOOLS_TRACER_CAPTURE_RESPONSE` | N/A
+**Capture Errors** | Captures Lambda or method exception as metadata |  `POWERTOOLS_TRACER_CAPTURE_ERROR` | N/A
+
 ### Permissions
 
 Before your use this utility, your AWS Lambda function [must have permissions](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html#services-xray-permissions) to send traces to AWS X-Ray.
@@ -63,7 +71,7 @@ You can quickly start by importing the `Tracer` class, initialize it outside the
     // OR tracer = Tracer({ service: 'example' });
 
     class Lambda {
-        @tracer.captureLambdaHanlder()
+        @tracer.captureLambdaHandler()
         public handler(event: any, context: any) {
             ...
         }
@@ -79,27 +87,33 @@ You can quickly start by importing the `Tracer` class, initialize it outside the
     import { Tracer } from '@aws-lambda-powertools/tracer';
 
     const tracer = Tracer(); // Sets service via env var
-    // OR tracer = Tracer({ service: 'example' });
+    // OR tracer = Tracer({ service: 'serverlessAirline' });
 
     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}`);
+        // Create subsegment for the function & set it as active
+        const subsegment = segment.addNewSubsegment(`## ${process.env._HANDLER}`);
+        tracer.setSegment(subsegment);
+
+        // Annotate the subsegment with the cold start & serviceName
         tracer.annotateColdStart();
         tracer.addServiceNameAnnotation();
 
         let res;
         try {
             res = ...
             // Add the response as metadata 
-            tracer.addResponseAsMetadata(res, context.functionName);
+            tracer.addResponseAsMetadata(res, process.env._HANDLER);
         } catch (err) {
             // Add the error as metadata
             tracer.addErrorAsMetadata(err as Error);
+            throw err;
         }
 
         // Close subsegment (the AWS Lambda one is closed automatically)
-        handlerSegment.close();
+        subsegment.close();
+        // Set the facade segment as active again
+        tracer.setSegment(segment);
 
         return res;
     }
@@ -109,6 +123,7 @@ When using the `captureLambdaHandler` decorator or middleware, Tracer performs t
 
 * Handles the lifecycle of the subsegment
 * Creates a `ColdStart` annotation to easily filter traces that have had an initialization overhead
+* Creates a `ServiceName` annotation to easily filter traces that have a specific service name
 * Captures any response, or full exceptions generated by the handler, and include as tracing metadata
 
 ### Annotations & Metadata
@@ -123,10 +138,10 @@ When using the `captureLambdaHandler` decorator or middleware, Tracer performs t
     ```typescript hl_lines="6"
     import { Tracer } from '@aws-lambda-powertools/tracer';
 
-    const tracer = new Tracer({ serviceName: 'my-service' });
+    const tracer = new Tracer({ serviceName: 'serverlessAirline' });
 
     export const handler = async (_event: any, _context: any) => {
-        tracer.putAnnotation('PaymentStatus', "SUCCESS");
+        tracer.putAnnotation('successfulBooking', true);
     }
     ```
 === "Metadata"
@@ -135,11 +150,11 @@ When using the `captureLambdaHandler` decorator or middleware, Tracer performs t
     ```typescript hl_lines="7"
     import { Tracer } from '@aws-lambda-powertools/tracer';
 
-    const tracer = new Tracer({ serviceName: 'my-service' });
+    const tracer = new Tracer({ serviceName: 'serverlessAirline' });
 
     export const handler = async (_event: any, _context: any) => {
         const res = someLogic();
-        tracer.putMetadata('PaymentResponse', res);
+        tracer.putMetadata('paymentResponse', res);
     }
     ```
 
@@ -178,29 +193,32 @@ You can trace other methods using the `captureMethod` decorator or manual instru
 
 === "Manual"
 
-    ```typescript hl_lines="2 8-9 15 18 22"
+    ```typescript hl_lines="6 8-9 15 23 25"
     import { Tracer } from '@aws-lambda-powertools/tracer';
-    import { Segment } from 'aws-xray-sdk-core';
 
-    const tracer = new Tracer({ serviceName: 'my-service' });
+    const tracer = new Tracer({ serviceName: 'serverlessAirline' });
 
     const chargeId = async () => {
-        // Create subsegment & set it as active
-        const subsegment = new Subsegment(`### chargeId`);
+        const parentSubsegment = tracer.getSegment(); // This is the subsegment currently active
+        // Create subsegment for the function & set it as active
+        const subsegment = parentSubsegment.addNewSubsegment(`### chargeId`);
         tracer.setSegment(subsegment);
 
         let res;
         try {
             res = await someLogic(); // Do something
             // Add the response as metadata
-            tracer.putMetadata(`chargeId response`, data);
+            tracer.addResponseAsMetadata(res, 'chargeId');
         } catch (err) {
             // Add the error as metadata
-            subsegment.addError(err, false);
+            tracer.addErrorAsMetadata(err as Error);
+            throw err;
         }
 
-        // Close subsegment
+        // Close subsegment (the AWS Lambda one is closed automatically)
         subsegment.close();
+        // Set the facade segment as active again
+        tracer.setSegment(parentSubsegment);
 
         return res;
     }

docs/index.md

@@ -40,9 +40,9 @@ This project separates core utilities that will be available in other runtimes v
 | ------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------- |
 | **POWERTOOLS_SERVICE_NAME** | Sets service name used for tracing namespace, metrics dimension and structured logging | All | `"service_undefined"` |
 | **POWERTOOLS_METRICS_NAMESPACE** | Sets namespace used for metrics | [Metrics](./core/metrics) | `None` |
-| **POWERTOOLS_TRACE_DISABLED** | Explicitly disables tracing | [Tracing](./core/tracer) | `false` |
-| **POWERTOOLS_TRACER_CAPTURE_RESPONSE** | Captures Lambda or method return as metadata. | [Tracing](./core/tracer) | `true` |
-| **POWERTOOLS_TRACER_CAPTURE_ERROR** | Captures Lambda or method exception as metadata. | [Tracing](./core/tracer) | `true` |
+| **POWERTOOLS_TRACE_ENABLED** | Explicitly enables/disables tracing | [Tracing](./core/tracer) | `true` |
+| **POWERTOOLS_TRACER_CAPTURE_RESPONSE** | Captures Lambda or method return as metadata | [Tracing](./core/tracer) | `true` |
+| **POWERTOOLS_TRACER_CAPTURE_ERROR** | Captures Lambda or method exception as metadata | [Tracing](./core/tracer) | `true` |
 | **POWERTOOLS_LOGGER_LOG_EVENT** | Logs incoming event | [Logging](./core/logger) | `false` |
 | **POWERTOOLS_LOGGER_SAMPLE_RATE** | Debug log sampling | [Logging](./core/logger) | `0` |
 | **POWERTOOLS_LOG_DEDUPLICATION_DISABLED** | Disables log deduplication filter protection to use Pytest Live Log feature | [Logging](./core/logger) | `false` |

packages/tracing/README.md

@@ -26,7 +26,7 @@ If you use function-based Lambda handlers you can use the [captureLambdaHandler(
 import { Tracer, captureLambdaHandler } from '@aws-lambda-powertools/tracer';
 import middy from '@middy/core';
 
-const tracer = new Tracer({ serviceName: 'my-service' });
+const tracer = new Tracer({ serviceName: 'serverlessAirline' });
 
 export const handler = middy(async (_event: any, _context: any) => {
     ...
@@ -44,7 +44,7 @@ If instead you use TypeScript Classes to wrap your Lambda handler you can use th
 ```typescript
 import { Tracer } from '@aws-lambda-powertools/tracer';
 
-const tracer = new Tracer({ serviceName: 'my-service' });
+const tracer = new Tracer({ serviceName: 'serverlessAirline' });
 
 class Lambda {
     @tracer.captureLambdaHandler()
@@ -64,27 +64,33 @@ If you prefer to manually instrument your Lambda handler you can use the methods
 ```typescript
 import { Tracer } from '@aws-lambda-powertools/tracer';
 
-const tracer = new Tracer({ serviceName: 'my-service' });
+const tracer = new Tracer({ serviceName: 'serverlessAirline' });
 
 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}`);
+    // Create subsegment for the function & set it as active
+    const subsegment = segment.addNewSubsegment(`## ${process.env._HANDLER}`);
+    tracer.setSegment(subsegment);
+
+    // Annotate the subsegment with the cold start & serviceName
     tracer.annotateColdStart();
     tracer.addServiceNameAnnotation();
 
     let res;
     try {
         res = ...
         // Add the response as metadata 
-        tracer.addResponseAsMetadata(res, context.functionName);
+        tracer.addResponseAsMetadata(res, process.env._HANDLER);
     } catch (err) {
         // Add the error as metadata
         tracer.addErrorAsMetadata(err as Error);
+        throw err;
     }
 
     // Close subsegment (the AWS Lambda one is closed automatically)
-    handlerSegment.close();
+    subsegment.close();
+    // Set the facade segment as active again
+    tracer.setSegment(segment);
 
     return res;
 }