diff --git a/docs/core/tracer.md b/docs/core/tracer.md
index c9c0b79cf0..c8dab4003c 100644
--- a/docs/core/tracer.md
+++ b/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>
diff --git a/docs/snippets/tracer/putAnnotation.ts b/docs/snippets/tracer/putAnnotation.ts
index c83363417f..fdff8108e5 100644
--- a/docs/snippets/tracer/putAnnotation.ts
+++ b/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)!
 };
diff --git a/docs/snippets/tracer/putMetadata.ts b/docs/snippets/tracer/putMetadata.ts
index 4458907925..5b900a138c 100644
--- a/docs/snippets/tracer/putMetadata.ts
+++ b/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)!
 };