chore(tracer): quality of life improvements (#337)

* Moved to common packages

* Updated docs

* Update main docs

* Exposed addResponseAsMetadata

* Exposed addErrorAsMetadata

* Exposed annotateColdStarted

* Feature parity w/ Python #851

* Feature parity w/ Python #861

* Revisited middleware implementation

* Fixed typo in jsdocs

* Reverted to local context/event usage in tests

* Update packages/tracing/src/Tracer.ts

Co-authored-by: Sara Gerion <[email protected]>

* Update packages/tracing/README.md

Co-authored-by: Sara Gerion <[email protected]>

* Update packages/tracing/README.md

Co-authored-by: Sara Gerion <[email protected]>

* Update packages/tracing/README.md

Co-authored-by: Sara Gerion <[email protected]>

Co-authored-by: Sara Gerion <[email protected]>

Author: dreamorosi

Diff for: 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
@@ -75,32 +75,31 @@ You can quickly start by importing the `Tracer` class, initialize it outside the
 
 === "Manual"
 
-    ```typescript hl_lines="1-2 4 9-10 12 18 21 25"
+    ```typescript hl_lines="1 3 7 9 11 17 20 24"
     import { Tracer } from '@aws-lambda-powertools/tracer';
-    import { Segment } from 'aws-xray-sdk-core';
 
     const tracer = Tracer(); // Sets service via env var
     // OR tracer = Tracer({ service: 'example' });
 
     export const handler = async (_event: any, context: any) => {
-        // Create subsegment & set it as active
-        const subsegment = new Subsegment(`## ${context.functionName}`);
-        tracer.setSegment(subsegment);
-        // Add the ColdStart annotation
-        this.putAnnotation('ColdStart', tracer.coldStart);
+        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.addServiceNameAnnotation();
 
         let res;
         try {
-            res = await someLogic(); // Do something
-            // Add the response as metadata
-            tracer.putMetadata(`${context.functionName} response`, data);
+            res = ...
+            // Add the response as metadata 
+            tracer.addResponseAsMetadata(res, context.functionName);
         } catch (err) {
             // Add the error as metadata
-            subsegment.addError(err, false);
+            tracer.addErrorAsMetadata(err as Error);
         }
-
-        // Close subsegment
-        subsegment.close();
+    
+        // Close subsegment (the AWS Lambda one is closed automatically)
+        handlerSegment.close();
 
         return res;
     }