Docs: extract Tracer code snippets in separate files

[dreamorosi]

What were you searching in the docs?

Currently the code snippets in the documentation under the Tracer's section are hardcoded as part of the page's markdown.

This authoring experience, which doesn't provide linting, is error prone, which causes issues in the docs and in turns to users.

This issue is part of a larger effort being tracked at #729.

Is this related to an existing documentation section?

https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/tracer/

How can we improve?

The code snippets should be extracted to their own separate files, placed under docs/snippets/tracer.

So for instance, the first snippet that currently reads:

import { Tracer } from '@aws-lambda-powertools/tracer';

const tracer = new Tracer({ serviceName: 'serverlessAirline' });

export const handler = async (_event, _context): Promise<void> => {
    // ...
};

would be replaced with:

--8<-- "docs/snippets/tracer/basicUsage.ts"

And the content should be placed in its own file at the path: docs/snippets/tracer/basicUsage.ts.

This applies to all TypeScript code snippets of the page.

Got a suggestion in mind?

No response

Acknowledgment

• I understand the final update might be different from my proposed suggestion, or refused.

[niko-achilles]

@dreamorosi i have the location for each snippet for tracer docs/snippets/tracer
Give me the names of each snippet for tracer as part of the acceptance criteria and i can start doing.

Identified 18 snippets for tracer . I use this tracer view, because of the flat structure ;)

1. snippet in section usage - handler.ts
   name of snippet: ?.ts

2. snippet in section Example using AWS Serverless Application Model SAM - handler.ts
   name of snippet: ?.ts

3. snippet in section Lambda handler - Middy Middleware
   name of snippet: ?.ts

4. snippet in section Lambda Handler - Decorator
   name of snippet: ?.ts

5. [snippet in section Lambda Handler - Manual]((https://github.com/awslabs/aws-lambda-powertools-typescript/blob/main/docs/core/tracer.md#lambda-handler)
   name of snippet: ?.ts

6. snippet in section Annotations & Metadata - Annotations
   name of snippet: ?.ts

7. snippet in section Annotations & Metadata - Metadata
   name of snippet: ?.ts

8. snippet in section Methods - Decorator
   name of snippet : ?.ts

9. snippet in section Methods - Manual
   name of snippet : ?.ts

10. snippet in section Patching AWS SDK clients - index.ts
    name of snippet : ?.ts

11. snippet in section Patching AWS SDK clients - index.ts
    name of snippet : ?.ts

12. snippet in section Patching AWS SDK clients - index.ts
    name of snippet : ?.ts

13. snippet in section Tracing HTTP requests - index.ts
    name of snippet: ?.ts

14. snippet in section Advanced - method.ts
    name of snippet: ?.ts

15. snippet in section Advanced - handler.ts
    name of snippet: ?.ts

16. snippet in section Advanced - middy.ts
    name of snippet: ?.ts

17. snippet in section Access AWS X-Ray Root Trace ID - index.ts
    name of snippet: ?.ts

18. snippet in section Escape hatch mechanism - index.ts
    name of snippet: ?.ts

[dreamorosi]

Hey Niko, I have assigned the issue to you.

I think these names could work:

1. basicUsage.ts
2. sam.ts
3. middy.ts
4. decorator.ts
5. manual.ts
6. putAnnotation.ts
7. putMetadata.ts
8. captureMethodDecorator.ts
9. captureMethodManual.ts
10. captureAWSv3.ts
11. captureAWSAll.ts
12. captureAWS.ts
13. captureHTTP.ts
14. disableCaptureResponseMethod.ts
15. disableCaptureResponseHandler.ts
16. disableCaptureResponseMiddy.ts
17. accessRootTraceId.ts
18. escapeHatch.ts

Notes:

• In all of the examples, you can remove both event and context from the handler signature, example.
• Number 8 has an error, the signature of the method should be async public getChargeId(): string {, this will fix Docs: Example of tracer.captureMethod() should demo in async instead of sync function #1203
• Number 14 has an error, the line @tracer.captureMethod({ captureResult: false }) should be @tracer.captureMethod({ captureResponse: false }), see type definition.

If you have any question please let me know, thanks!

[github-actions]

⚠️ COMMENT VISIBILITY WARNING ⚠️

Comments on closed issues are hard for our team to see.
If you need more assistance, please either tag a team member or open a new issue that references this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.