Docs: extract Logger code snippets in separate files

[dreamorosi]

What were you searching in the docs?

Currently the code snippets in the documentation under the Logger'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/logger/

How can we improve?

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

So for instance, the first snippet that currently reads:

import { Logger } from '@aws-lambda-powertools/logger';

const logger = new Logger({ serviceName: 'serverlessAirline' });

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

would be replaced with:

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

And the content should be placed in its own file at the path: docs/snippets/logger/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 Give me the names of the code snippets for Logger so that i can start doing.

Code Snippets identified:

1. section Usage - handler.ts
2. section Example using AWS Serverless Application Model (SAM) - handler.ts
3. section Capturing Lambda context info - Middy Middleware
4. section Capturing Lambda context info - Decorator
5. section Capturing Lambda context info - Manual
6. section Loging incoming event - Middy Middleware
7. section Loging incoming event - Decorator
8. section Appending persistent additional log keys and values - handler.ts
9. section Clearing all state - Middy Middleware
10. section Clearing all state - Decorator
11. section Appending additional data to a single log item - handler.ts
12. section Logging errors - handler.ts
13. section Using multiple Logger instances across your code - handler.ts
14. section Sampling logs - handler.ts
15. section Custom Log formatter (Bring Your Own Formatter) - handler.ts
16. section Custom Log formatter (Bring Your Own Formatter) - utils/formatters/MyCompanyLogFormatter.ts
17. section Testing your code - handler.test.ts

[dreamorosi]

Here:

1. basicUsage.ts
2. sam.ts
3. middy.ts
4. decorator.ts
5. manual.ts
6. eventMiddy.ts
7. eventDecorator.ts
8. appendKeys.ts
9. clearStateMiddy.ts
10. clearStateDecorator.ts
11. extraData.ts
12. logError.ts
13. createChild.ts
14. logSampling.ts
15. bringYourOwnFormatterHandler.ts
16. bringYourOwnFormatterClass.ts
17. unitTesting.ts

[niko-achilles]

How can we improve?
The code snippets should be extracted to their own separate files, placed under docs/snippets/tracer.

Please correct the path docs/snippets/tracer under How can we improve ? in #1220 (comment). It should be as I assume docs/snippets/logger

So for acceptance we have the 17 named code snippets : #1220 (comment)

and the location docs/snippets/logger of the Logger code snippets .

Is that ok @dreamorosi ?

[dreamorosi]

Yes, that's okay.

Corrected.

[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.