Merge branch 'awslabs:develop' into develop

Author: am29d

.github/workflows/publish.yml

@@ -48,7 +48,7 @@ jobs:
       with:
         fetch-depth: 0
     - name: Set up Python
-      uses: actions/setup-python@v2.2.2
+      uses: actions/setup-python@v2.3.1
       with:
         python-version: "3.8"
     - name: Set release notes tag

.github/workflows/python_build.yml

@@ -23,7 +23,7 @@ jobs:
     steps:
       - uses: actions/checkout@v1
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2.2.2
+        uses: actions/setup-python@v2.3.1
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies

.github/workflows/python_docs.yml

@@ -17,7 +17,7 @@ jobs:
         with:
           fetch-depth: 0
       - name: Set up Python
-        uses: actions/setup-python@v2.2.2
+        uses: actions/setup-python@v2.3.1
         with:
           python-version: "3.8"
       - name: Install dependencies

.github/workflows/rebuild_latest_docs.yml

@@ -25,7 +25,7 @@ jobs:
       with:
         fetch-depth: 0
     - name: Set up Python
-      uses: actions/setup-python@v2.2.2
+      uses: actions/setup-python@v2.3.1
       with:
         python-version: "3.8"
     - name: Set release notes tag

Makefile

@@ -20,6 +20,9 @@ test:
 	poetry run pytest -m "not perf" --cov=aws_lambda_powertools --cov-report=xml
 	poetry run pytest --cache-clear tests/performance
 
+unit-test:
+	poetry run pytest tests/unit
+
 coverage-html:
 	poetry run pytest -m "not perf" --cov=aws_lambda_powertools --cov-report=html
 

README.md

@@ -47,7 +47,7 @@ With [pip](https://pip.pypa.io/en/latest/index.html) installed, run: ``pip insta
 
 ## Connect
 
-* **AWS Developers Slack**: `#lambda-powertools`** - **[Invite, if you don't have an account](https://join.slack.com/t/awsdevelopers/shared_invite/zt-gu30gquv-EhwIYq3kHhhysaZ2aIX7ew)**
+* **AWS Developers Slack**: `#lambda-powertools`** - **[Invite, if you don't have an account](https://join.slack.com/t/awsdevelopers/shared_invite/zt-yryddays-C9fkWrmguDv0h2EEDzCqvw)**
 * **Email**: [email protected]
 
 ## License

aws_lambda_powertools/event_handler/api_gateway.py

@@ -664,6 +664,10 @@ def include_router(self, router: "Router", prefix: Optional[str] = None) -> None
         prefix : str, optional
             An optional prefix to be added to the originally defined rule
         """
+
+        # Add reference to parent ApiGatewayResolver to support use cases where people subclass it to add custom logic
+        router.api_resolver = self
+
         for route, func in router._routes.items():
             if prefix:
                 rule = route[0]
@@ -678,6 +682,7 @@ class Router(BaseRouter):
 
     def __init__(self):
         self._routes: Dict[tuple, Callable] = {}
+        self.api_resolver: Optional[BaseRouter] = None
 
     def route(
         self,

aws_lambda_powertools/metrics/metric.py

@@ -1,7 +1,7 @@
 import json
 import logging
 from contextlib import contextmanager
-from typing import Dict, Optional, Union
+from typing import Dict, Optional, Union, Generator
 
 from .base import MetricManager, MetricUnit
 
@@ -61,7 +61,7 @@ def add_metric(self, name: str, unit: Union[MetricUnit, str], value: float) -> N
 
 
 @contextmanager
-def single_metric(name: str, unit: MetricUnit, value: float, namespace: Optional[str] = None):
+def single_metric(name: str, unit: MetricUnit, value: float, namespace: Optional[str] = None) -> Generator[SingleMetric, None, None]:
     """Context manager to simplify creation of a single metric
 
     Example

aws_lambda_powertools/tracing/tracer.py

@@ -17,7 +17,6 @@
 logger = logging.getLogger(__name__)
 
 aws_xray_sdk = LazyLoader(constants.XRAY_SDK_MODULE, globals(), constants.XRAY_SDK_MODULE)
-aws_xray_sdk.core = LazyLoader(constants.XRAY_SDK_CORE_MODULE, globals(), constants.XRAY_SDK_CORE_MODULE)  # type: ignore # noqa: E501
 
 
 class Tracer:
@@ -137,7 +136,7 @@ def handler(event: dict, context: Any) -> Dict:
     """
 
     _default_config: Dict[str, Any] = {
-        "service": "service_undefined",
+        "service": "",
         "disabled": False,
         "auto_patch": True,
         "patch_modules": None,
@@ -156,7 +155,7 @@ def __init__(
         self.__build_config(
             service=service, disabled=disabled, auto_patch=auto_patch, patch_modules=patch_modules, provider=provider
         )
-        self.provider: BaseProvider = self._config["provider"]
+        self.provider = self._config["provider"]
         self.disabled = self._config["disabled"]
         self.service = self._config["service"]
         self.auto_patch = self._config["auto_patch"]
@@ -167,10 +166,8 @@ def __init__(
         if self.auto_patch:
             self.patch(modules=patch_modules)
 
-        # Set the streaming threshold to 0 on the default recorder to force sending
-        # subsegments individually, rather than batching them.
-        # See https://github.com/awslabs/aws-lambda-powertools-python/issues/283
-        aws_xray_sdk.core.xray_recorder.configure(streaming_threshold=0)  # noqa: E800
+        if self._is_xray_provider():
+            self._disable_xray_trace_batching()
 
     def put_annotation(self, key: str, value: Union[str, numbers.Number, bool]):
         """Adds annotation to existing segment or subsegment
@@ -239,9 +236,9 @@ def patch(self, modules: Optional[Sequence[str]] = None):
             return
 
         if modules is None:
-            aws_xray_sdk.core.patch_all()
+            self.provider.patch_all()
         else:
-            aws_xray_sdk.core.patch(modules)
+            self.provider.patch(modules)
 
     def capture_lambda_handler(
         self,
@@ -304,11 +301,15 @@ def handler(event, context):
         def decorate(event, context, **kwargs):
             with self.provider.in_subsegment(name=f"## {lambda_handler_name}") as subsegment:
                 global is_cold_start
+                logger.debug("Annotating cold start")
+                subsegment.put_annotation(key="ColdStart", value=is_cold_start)
+
                 if is_cold_start:
-                    logger.debug("Annotating cold start")
-                    subsegment.put_annotation(key="ColdStart", value=True)
                     is_cold_start = False
 
+                if self.service:
+                    subsegment.put_annotation(key="Service", value=self.service)
+
                 try:
                     logger.debug("Calling lambda handler")
                     response = lambda_handler(event, context, **kwargs)
@@ -742,7 +743,8 @@ def __build_config(
         is_disabled = disabled if disabled is not None else self._is_tracer_disabled()
         is_service = resolve_env_var_choice(choice=service, env=os.getenv(constants.SERVICE_NAME_ENV))
 
-        self._config["provider"] = provider or self._config["provider"] or aws_xray_sdk.core.xray_recorder
+        # Logic: Choose overridden option first, previously cached config, or default if available
+        self._config["provider"] = provider or self._config["provider"] or self._patch_xray_provider()
         self._config["auto_patch"] = auto_patch if auto_patch is not None else self._config["auto_patch"]
         self._config["service"] = is_service or self._config["service"]
         self._config["disabled"] = is_disabled or self._config["disabled"]
@@ -751,3 +753,28 @@ def __build_config(
     @classmethod
     def _reset_config(cls):
         cls._config = copy.copy(cls._default_config)
+
+    def _patch_xray_provider(self):
+        # Due to Lazy Import, we need to activate `core` attrib via import
+        # we also need to include `patch`, `patch_all` methods
+        # to ensure patch calls are done via the provider
+        from aws_xray_sdk.core import xray_recorder
+
+        provider = xray_recorder
+        provider.patch = aws_xray_sdk.core.patch
+        provider.patch_all = aws_xray_sdk.core.patch_all
+
+        return provider
+
+    def _disable_xray_trace_batching(self):
+        """Configure X-Ray SDK to send subsegment individually over batching
+        Known issue: https://github.com/awslabs/aws-lambda-powertools-python/issues/283
+        """
+        if self.disabled:
+            logger.debug("Tracing has been disabled, aborting streaming override")
+            return
+
+        aws_xray_sdk.core.xray_recorder.configure(streaming_threshold=0)
+
+    def _is_xray_provider(self):
+        return "aws_xray_sdk" in self.provider.__module__

aws_lambda_powertools/utilities/idempotency/base.py

@@ -56,7 +56,7 @@ def __init__(
         self.fn_args = function_args
         self.fn_kwargs = function_kwargs
 
-        persistence_store.configure(config)
+        persistence_store.configure(config, self.function.__name__)
         self.persistence_store = persistence_store
 
     def handle(self) -> Any:

aws_lambda_powertools/utilities/idempotency/persistence/base.py

@@ -112,6 +112,7 @@ class BasePersistenceLayer(ABC):
 
     def __init__(self):
         """Initialize the defaults"""
+        self.function_name = ""
         self.configured = False
         self.event_key_jmespath: Optional[str] = None
         self.event_key_compiled_jmespath = None
@@ -124,15 +125,19 @@ def __init__(self):
         self._cache: Optional[LRUDict] = None
         self.hash_function = None
 
-    def configure(self, config: IdempotencyConfig) -> None:
+    def configure(self, config: IdempotencyConfig, function_name: Optional[str] = None) -> None:
         """
         Initialize the base persistence layer from the configuration settings
 
         Parameters
         ----------
         config: IdempotencyConfig
             Idempotency configuration settings
+        function_name: str, Optional
+            The name of the function being decorated
         """
+        self.function_name = f"{os.getenv(constants.LAMBDA_FUNCTION_NAME_ENV, 'test-func')}.{function_name or ''}"
+
         if self.configured:
             # Prevent being reconfigured multiple times
             return
@@ -178,8 +183,7 @@ def _get_hashed_idempotency_key(self, data: Dict[str, Any]) -> str:
             warnings.warn(f"No value found for idempotency_key. jmespath: {self.event_key_jmespath}")
 
         generated_hash = self._generate_hash(data=data)
-        function_name = os.getenv(constants.LAMBDA_FUNCTION_NAME_ENV, "test-func")
-        return f"{function_name}#{generated_hash}"
+        return f"{self.function_name}#{generated_hash}"
 
     @staticmethod
     def is_missing_idempotency_key(data) -> bool:

docs/core/event_handler/api_gateway.md

@@ -1027,43 +1027,42 @@ When necessary, you can set a prefix when including a router object. This means
 
 #### Sample layout
 
-!!! info "We use ALB to demonstrate that the UX remains the same"
-
-This sample project contains an Users function with two distinct set of routes, `/users` and `/health`. The layout optimizes for code sharing, no custom build tooling, and it uses [Lambda Layers](../../index.md#lambda-layer) to install Lambda Powertools.
+This sample project contains a Users function with two distinct set of routes, `/users` and `/health`. The layout optimizes for code sharing, no custom build tooling, and it uses [Lambda Layers](../../index.md#lambda-layer) to install Lambda Powertools.
 
 === "Project layout"
 
 
-    ```python hl_lines="6 8 10-13"
+    ```python hl_lines="1 8 10 12-15"
     .
-    ├── Pipfile                   # project app & dev dependencies; poetry, pipenv, etc.
+    ├── Pipfile                    # project app & dev dependencies; poetry, pipenv, etc.
     ├── Pipfile.lock
-    ├── mypy.ini                  # namespace_packages = True
-    ├── .env                      # VSCode only. PYTHONPATH="users:${PYTHONPATH}"
-    ├── users
-    │   ├── requirements.txt      # sam build detect it automatically due to CodeUri: users, e.g. pipenv lock -r > users/requirements.txt
-    │   ├── lambda_function.py    # this will be our users Lambda fn; it could be split in folders if we want separate fns same code base
-    │   ├── constants.py
-    │   └── routers               # routers module
+    ├── README.md
+    ├── src
     │       ├── __init__.py
-    │       ├── users.py          # /users routes, e.g. from routers import users; users.router
-    │       ├── health.py         # /health routes, e.g. from routers import health; health.router
-    ├── template.yaml             # SAM template.yml, CodeUri: users, Handler: users.main.lambda_handler
+    │       ├── requirements.txt   # sam build detect it automatically due to CodeUri: src, e.g. pipenv lock -r > src/requirements.txt
+    │       └── users
+    │           ├── __init__.py
+    │           ├── main.py       # this will be our users Lambda fn; it could be split in folders if we want separate fns same code base
+    │           └── routers       # routers module
+    │               ├── __init__.py
+    │               ├── health.py # /users routes, e.g. from routers import users; users.router
+    │               └── users.py  # /users routes, e.g. from .routers import users; users.router
+    ├── template.yml              # SAM template.yml, CodeUri: src, Handler: users.main.lambda_handler
     └── tests
         ├── __init__.py
         ├── unit
         │   ├── __init__.py
-        │   └── test_users.py    # unit tests for the users router
-        │   └── test_health.py   # unit tests for the health router
+        │   └── test_users.py     # unit tests for the users router
+        │   └── test_health.py    # unit tests for the health router
         └── functional
             ├── __init__.py
-            ├── conftest.py      # pytest fixtures for the functional tests
-            └── test_lambda_function.py    # functional tests for the main lambda handler
+            ├── conftest.py       # pytest fixtures for the functional tests
+            └── test_main.py      # functional tests for the main lambda handler
     ```
 
 === "template.yml"
 
-    ```yaml  hl_lines="20-21"
+    ```yaml  hl_lines="22-23"
     AWSTemplateFormatVersion: '2010-09-09'
     Transform: AWS::Serverless-2016-10-31
     Description: Example service with multiple routes
@@ -1073,6 +1072,8 @@ This sample project contains an Users function with two distinct set of routes,
             MemorySize: 512
             Runtime: python3.9
             Tracing: Active
+            Architectures:
+                - x86_64
             Environment:
                 Variables:
                     LOG_LEVEL: INFO
@@ -1083,11 +1084,11 @@ This sample project contains an Users function with two distinct set of routes,
         UsersService:
             Type: AWS::Serverless::Function
             Properties:
-                Handler: lambda_function.lambda_handler
-                CodeUri: users
+                Handler: users.main.lambda_handler
+                CodeUri: src
                 Layers:
                     # Latest version: https://awslabs.github.io/aws-lambda-powertools-python/latest/#lambda-layer
-                    - !Sub arn:aws:lambda:${AWS::Region}:017000801446:layer:AWSLambdaPowertoolsPython:3
+                    - !Sub arn:aws:lambda:${AWS::Region}:017000801446:layer:AWSLambdaPowertoolsPython:4
                 Events:
                     ByUser:
                         Type: Api
@@ -1119,7 +1120,7 @@ This sample project contains an Users function with two distinct set of routes,
             Value: !GetAtt UsersService.Arn
     ```
 
-=== "users/lambda_function.py"
+=== "src/users/main.py"
 
     ```python hl_lines="9 15-16"
     from typing import Dict
@@ -1130,23 +1131,23 @@ This sample project contains an Users function with two distinct set of routes,
     from aws_lambda_powertools.logging.correlation_paths import APPLICATION_LOAD_BALANCER
     from aws_lambda_powertools.utilities.typing import LambdaContext
 
-    from routers import health, users
+    from .routers import health, users
 
     tracer = Tracer()
     logger = Logger()
-    app = ApiGatewayResolver(proxy_type=ProxyEventType.ALBEvent)
+    app = ApiGatewayResolver(proxy_type=ProxyEventType.APIGatewayProxyEvent)
 
     app.include_router(health.router)
     app.include_router(users.router)
 
 
-    @logger.inject_lambda_context(correlation_id_path=APPLICATION_LOAD_BALANCER)
+    @logger.inject_lambda_context(correlation_id_path=API_GATEWAY_REST)
     @tracer.capture_lambda_handler
     def lambda_handler(event: Dict, context: LambdaContext):
         return app.resolve(event, context)
     ```
 
-=== "users/routers/health.py"
+=== "src/users/routers/health.py"
 
     ```python hl_lines="4 6-7 10"
     from typing import Dict
@@ -1169,7 +1170,7 @@ This sample project contains an Users function with two distinct set of routes,
     ```python  hl_lines="3"
     import json
 
-    from users import main  # follows namespace package from root
+    from src.users import main  # follows namespace package from root
 
 
     def test_lambda_handler(apigw_event, lambda_context):
@@ -1180,16 +1181,6 @@ This sample project contains an Users function with two distinct set of routes,
         assert ret["body"] == expected
     ```
 
-=== ".env"
-
-    > Note: It is not needed for PyCharm (select folder as source).
-
-    This is necessary for Visual Studio Code, so integrated tooling works without failing import.
-
-    ```bash
-    PYTHONPATH="users:${PYTHONPATH}"
-    ```
-
 ### Considerations
 
 This utility is optimized for fast startup, minimal feature set, and to quickly on-board customers familiar with frameworks like Flask — it's not meant to be a fully fledged framework.