docs(tracer): split and lint code snippets

[heitorlessa]

Issue number: #1009

Summary

Changes

Please provide a summary of what's being changed

This PR splits code snippets into a top-level examples folder. Formatting and linting (make lint) were adjusted to include examples folder. We also introduce cfn-lint within pre-commit hooks to selectively lint changed infra files within examples folder.

The only downside is that documentation needs to be rebuilt/rerun when example files are changed, as live change won't reflect files that are included.

Convention

We'll keep all examples under examples folder. Each feature will have its own source code that match what's in the documentation, followed by one or more infrastructure as code customers could use in the future.

Example for Tracer

examples
└── tracer
    ├── cdk
    │   └── all_cdk_project_files, dependencies, etc.
    ├── sam
    │   └── template.yaml
    ├── src
    │   └── capture_lambda_handler.py
    └── terraform

Caveat

We need to ensure Lambda Powertools dependency/layer is used. In the case of Layers, we will need to upgrade the Layer version within examples as part of each release - @am29d your input is crucial here on the best way forward. Until Alex completes his Layer pipeline refactoring, we can build a workflow action to find/replace Layer ARN Version.

Another caveat is that cfn-lint dropped support for 3.6. We're using an official cfn-lint GitHub Actions as a workaround.

User experience

Please share what the user experience looks like before and after this change

Example of adding an invalid SAM template for a code snippet

Code quality example using our set of rules

Checklist

If your change doesn't seem to apply, please leave them unchecked.

• Meet tenets criteria
• I have performed a self-review of my this change
• Changes are tested
• Changes are documented
• PR title follows conventional commit semantics

Is this a breaking change?

RFC issue number:

Checklist:

• Migration process documented
• Implement warnings (if it can live side by side)

Acknowledgment

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.

---

View rendered docs/core/tracer.md

[heitorlessa]

feedback received from @sthulb ==> Approach B. Tested with SAM and SAM CLI for parent folder (..src/) and worked just fine. I'll carry on in an hour or so