From 34f2b1c95f90dada06a4053a8c3ac68c8a647d87 Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Thu, 21 Sep 2023 11:37:43 +0200 Subject: [PATCH] docs(tracer): update annotation & metadata docs to include full code ## Description of 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 **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. --- docs/core/tracer.md | 10 ++++++++-- docs/snippets/tracer/putAnnotation.ts | 6 ++++++ docs/snippets/tracer/putMetadata.ts | 6 ++++++ 3 files changed, 20 insertions(+), 2 deletions(-) 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). +
Screenshot of the Amazon CloudWatch Console showing an example of segments and subsegments generated and with metadata set for the handler
Tracer showcase - Handler Metadata
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 => { + 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 => { + const handlerSegment = tracer.getSegment()?.addNewSubsegment('### handler'); + handlerSegment && tracer.setSegment(handlerSegment); // (1)! + tracer.putMetadata('paymentResponse', { foo: 'bar', }); + + handlerSegment?.close(); + handlerSegment && tracer.setSegment(handlerSegment?.parent); // (2)! };