docs(tracer): update annotation & metadata docs to include full code

<!---
Instructions:
1. Make sure you follow our Contributing Guidelines: https://github.com/aws-powertools/powertools-lambda-typescript/blob/main/CONTRIBUTING.md
2. Please follow the template, and do not remove any section/item. If something is not applicable leave it empty, but leave it in the PR.
3. -->

## Description of your changes

<!---
Include here a summary of the change.

Please include also relevant motivation and context.

Add any applicable code snippets, links, screenshots, or other resources
that can help us verify your changes.
-->

This PR introduces changes to the code snippets found in the Tracer documentation and related to adding annotations and metadata to a segment.

The original snippets were mistakenly not handling the opening and closing of a custom subsegment and were instead suggesting to attempt annotating the `facade` segment.

This is a mistake because that segment is managed by the service and cannot be modified, resulting in an error.

The PR fixes this and shows the full code snippet.

### Related issues, RFCs

<!---
Add here the number (i.e. #42) to the Github Issue or RFC that is related to this PR.

Don't include any other text, otherwise the Github Issue will not be detected.

Note: If no issue is present the PR might get blocked and not be reviewed.
-->
**Issue number:** #1699

## Checklist

- [x] [My changes meet the tenets criteria](https://docs.powertools.aws.dev/lambda-typescript/#tenets)
- [x] I have performed a *self-review* of my own code
- [x] I have *commented* my code where necessary, particularly in areas that should be flagged with a TODO, or hard-to-understand areas
- [x] I have made corresponding changes to the *documentation*
- [x] My changes generate *no new warnings*
- [ ] I have *added tests* that prove my change is effective and works
- [x] The PR title follows the [conventional commit semantics](https://github.com/aws-powertools/powertools-lambda-typescript/blob/main/.github/semantic.yml#L2)

### Breaking change checklist

***Is it a breaking change?:*** NO

- [ ] I have documented the migration process
- [ ] I have added, implemented necessary warnings (if it can live side by side)

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

**Disclaimer**: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

Author: dreamorosi

docs/core/tracer.md

@@ -129,16 +129,22 @@ When using the `captureLambdaHandler` decorator or middleware, Tracer performs t
 === "Annotations"
     You can add annotations using `putAnnotation` method.
 
-    ```typescript hl_lines="9"
+    ```typescript hl_lines="12"
     --8<-- "docs/snippets/tracer/putAnnotation.ts"
     ```
+
+    1. When Lambda starts an invocation [the X-Ray SDk creates a segment called `facade`](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-subsegments.html#xray-sdk-nodejs-subsegments-lambda). This segment cannot be annotated or modified by your code, so you need to create a new subsegment. This is done automatically by Tracer when using the [decorator or middleware patterns](./tracer.md/#lambda-handler)
+    2. To correctly trace the current and subsequent invocations you need to restore the original segment, this is done automatically by Tracer when using the [decorator or middleware patterns](./tracer.md/#lambda-handler).
 === "Metadata"
     You can add metadata using `putMetadata` method.
 
-    ```typescript hl_lines="9-11"
+    ```typescript hl_lines="12-14"
     --8<-- "docs/snippets/tracer/putMetadata.ts"
     ```
 
+    1. When Lambda starts an invocation [the X-Ray SDk creates a segment called `facade`](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-subsegments.html#xray-sdk-nodejs-subsegments-lambda). This segment cannot be modified by your code, so you need to create a new subsegment. This is done automatically by Tracer when using the [decorator or middleware patterns](./tracer.md/#lambda-handler)
+    2. To correctly trace the current and subsequent invocations you need to restore the original segment, this is done automatically by Tracer when using the [decorator or middleware patterns](./tracer.md/#lambda-handler).
+
 <figure>
   <img src="../../media/tracer_utility_showcase_2.png" loading="lazy" alt="Screenshot of the Amazon CloudWatch Console showing an example of segments and subsegments generated and with metadata set for the handler"/>
   <figcaption>Tracer showcase - Handler Metadata</figcaption>

docs/snippets/tracer/putAnnotation.ts

@@ -6,5 +6,11 @@ export const handler = async (
   _event: unknown,
   _context: unknown
 ): Promise<void> => {
+  const handlerSegment = tracer.getSegment()?.addNewSubsegment('### handler');
+  handlerSegment && tracer.setSegment(handlerSegment); // (1)!
+
   tracer.putAnnotation('successfulBooking', true);
+
+  handlerSegment?.close();
+  handlerSegment && tracer.setSegment(handlerSegment?.parent); // (2)!
 };

docs/snippets/tracer/putMetadata.ts

@@ -6,7 +6,13 @@ export const handler = async (
   _event: unknown,
   _context: unknown
 ): Promise<void> => {
+  const handlerSegment = tracer.getSegment()?.addNewSubsegment('### handler');
+  handlerSegment && tracer.setSegment(handlerSegment); // (1)!
+
   tracer.putMetadata('paymentResponse', {
     foo: 'bar',
   });
+
+  handlerSegment?.close();
+  handlerSegment && tracer.setSegment(handlerSegment?.parent); // (2)!
 };