docs(tracer): snippets split, improved, and lint

[heitorlessa]

Issue number: #1260 (older PR)

Summary

NOTE: Accidentally hit merge in previous PR after agreeing on approach. Reusing previous body.

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.

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]

Tracer finalized. Here's how the structure looks like for other examples - names match features in docs to ease discovery. Examples are now fully typed and improved too.

 tree examples
examples
└── tracer
    ├── sam
    │   └── template.yaml
    ├── src
    │   ├── capture_lambda_handler.py
    │   ├── capture_method.py
    │   ├── capture_method_async.py
    │   ├── capture_method_async_concurrency.py
    │   ├── capture_method_context_manager.py
    │   ├── capture_method_generators.py
    │   ├── disable_capture_error.py
    │   ├── disable_capture_response.py
    │   ├── disable_capture_response_streaming_body.py
    │   ├── ignore_endpoints.py
    │   ├── patch_modules.py
    │   ├── put_trace_annotations.py
    │   ├── put_trace_metadata.py
    │   ├── sdk_escape_hatch.py
    │   ├── tracer_reuse.py
    │   ├── tracer_reuse_payment.py
    │   └── tracing_aiohttp.py
    └── template.yaml