diff --git a/.github/workflows/python_docs.yml b/.github/workflows/python_docs.yml index d168e1ae68a..3a6e15e5431 100644 --- a/.github/workflows/python_docs.yml +++ b/.github/workflows/python_docs.yml @@ -8,6 +8,7 @@ on: - "docs/**" - "CHANGELOG.md" - "mkdocs.yml" + - "examples/**" jobs: docs: @@ -20,10 +21,15 @@ jobs: uses: actions/setup-python@v4 with: python-version: "3.8" + # Maintenance: temporarily until we drop Python 3.6 and make cfn-lint a dev dependency + - name: Setup Cloud Formation Linter with Latest Version + uses: scottbrenner/cfn-lint-action@v2 - name: Install dependencies run: make dev - name: Lint documentation - run: make lint-docs + run: | + make lint-docs + cfn-lint examples/**/*.yaml - name: Setup doc deploy run: | git config --global user.name Docs deploy diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 97bdef15726..8a614f78968 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -30,9 +30,13 @@ repos: entry: poetry run flake8 language: system types: [python] - exclude: example - repo: https://github.com/igorshubovych/markdownlint-cli rev: "11c08644ce6df850480d98f628596446a526cbc6" # frozen: v0.31.1 hooks: - id: markdownlint args: ["--fix"] + - repo: https://github.com/aws-cloudformation/cfn-python-lint + rev: v0.61.1 + hooks: + - id: cfn-python-lint + files: examples/.*\.(yaml|yml)$ diff --git a/Makefile b/Makefile index 5ad35546f95..6173e3e310d 100644 --- a/Makefile +++ b/Makefile @@ -10,11 +10,11 @@ dev: pre-commit install format: - poetry run isort aws_lambda_powertools tests - poetry run black aws_lambda_powertools tests + poetry run isort aws_lambda_powertools tests examples + poetry run black aws_lambda_powertools tests examples lint: format - poetry run flake8 aws_lambda_powertools/* tests/* + poetry run flake8 aws_lambda_powertools tests examples lint-docs: docker run -v ${PWD}:/markdown 06kellyjac/markdownlint-cli "docs" diff --git a/docs/core/tracer.md b/docs/core/tracer.md index a773ecb52a8..963552c3e99 100644 --- a/docs/core/tracer.md +++ b/docs/core/tracer.md @@ -20,33 +20,16 @@ Tracer is an opinionated thin wrapper for [AWS X-Ray Python SDK](https://github. Before your use this utility, your AWS Lambda function [must have permissions](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html#services-xray-permissions) to send traces to AWS X-Ray. -```yaml hl_lines="6 9" title="AWS Serverless Application Model (SAM) example" -Resources: - HelloWorldFunction: - Type: AWS::Serverless::Function - Properties: - Runtime: python3.8 - Tracing: Active - Environment: - Variables: - POWERTOOLS_SERVICE_NAME: example +```yaml hl_lines="9 12" title="AWS Serverless Application Model (SAM) example" +--8<-- "examples/tracer/template.yaml" ``` ### Lambda handler You can quickly start by initializing `Tracer` and use `capture_lambda_handler` decorator for your Lambda handler. -```python hl_lines="1 3 6" title="Tracing Lambda handler with capture_lambda_handler" -from aws_lambda_powertools import Tracer - -tracer = Tracer() # Sets service via env var -# OR tracer = Tracer(service="example") - -@tracer.capture_lambda_handler -def handler(event, context): - charge_id = event.get('charge_id') - payment = collect_payment(charge_id) - ... +```python hl_lines="1 4 12" title="Tracing Lambda handler with capture_lambda_handler" +--8<-- "examples/tracer/src/capture_lambda_handler.py" ``` `capture_lambda_handler` performs these additional tasks to ease operations: diff --git a/examples/tracer/src/capture_lambda_handler.py b/examples/tracer/src/capture_lambda_handler.py new file mode 100644 index 00000000000..461a31cd213 --- /dev/null +++ b/examples/tracer/src/capture_lambda_handler.py @@ -0,0 +1,15 @@ +from aws_lambda_powertools import Tracer +from aws_lambda_powertools.utilities.typing import LambdaContext + +tracer = Tracer() # Sets service via POWERTOOLS_SERVICE_NAME env var +# OR tracer = Tracer(service="example") + + +def collect_payment(charge_id: str) -> str: + return f"dummy payment collected for charge: {charge_id}" + + +@tracer.capture_lambda_handler +def handler(event: dict, context: LambdaContext) -> str: + charge_id = event.get("charge_id") + return collect_payment(charge_id) diff --git a/examples/tracer/template.yaml b/examples/tracer/template.yaml new file mode 100644 index 00000000000..504661d634d --- /dev/null +++ b/examples/tracer/template.yaml @@ -0,0 +1,23 @@ +AWSTemplateFormatVersion: "2010-09-09" +Transform: AWS::Serverless-2016-10-31 +Description: AWS Lambda Powertools Tracer doc examples + +Globals: + Function: + Timeout: 5 + Runtime: python3.9 + Tracing: Active + Environment: + Variables: + POWERTOOLS_SERVICE_NAME: example + Layers: + # Find the latest Layer version in the official documentation + # https://awslabs.github.io/aws-lambda-powertools-python/latest/#lambda-layer + - !Sub arn:aws:lambda:${AWS::Region}:017000801446:layer:AWSLambdaPowertoolsPython:21 + +Resources: + CaptureLambdaHandlerExample: + Type: AWS::Serverless::Function + Properties: + CodeUri: src + Handler: capture_lambda_handler.handler