feature: ability to pass sampling_rate to logger setup so calls may get sampled in "debug" setup.

Author: danilohgds

.gitignore

@@ -291,5 +291,5 @@ $RECYCLE.BIN/
 # End of https://www.gitignore.io/api/osx,linux,python,windows,pycharm,visualstudiocode
 
 # Misc
-
-test_report
+test_report
+/.idea/*

python/aws_lambda_powertools/logging/logger.py

@@ -2,19 +2,22 @@
 import itertools
 import logging
 import os
+import random
 from distutils.util import strtobool
 from typing import Any, Callable, Dict
 
-from . import aws_lambda_logging
 from ..helper.models import MetricUnit, build_lambda_context_model, build_metric_unit_from_str
+from . import aws_lambda_logging
 
 logger = logging.getLogger(__name__)
 logger.setLevel(os.getenv("LOG_LEVEL", "INFO"))
 
 is_cold_start = True
 
 
-def logger_setup(service: str = "service_undefined", level: str = "INFO", **kwargs):
+def logger_setup(
+        service: str = "service_undefined", level: str = "INFO", sampling_rate: float = 0.0, **kwargs
+):
     """Setups root logger to format statements in JSON.
 
     Includes service name and any additional key=value into logs
@@ -26,13 +29,17 @@ def logger_setup(service: str = "service_undefined", level: str = "INFO", **kwar
         service name
     LOG_LEVEL: str
         logging level (e.g. INFO, DEBUG)
+    POWERTOOLS_SAMPLE_RATE: str
+        samping rate ranging from 0 to 1, float precision
 
     Parameters
     ----------
     service : str, optional
         service name to be appended in logs, by default "service_undefined"
     level : str, optional
         logging.level, by default "INFO"
+    sample_rate: float, optional
+        sample rate for debug calls within execution context defaults to 0
 
     Example
     -------
@@ -52,21 +59,36 @@ def logger_setup(service: str = "service_undefined", level: str = "INFO", **kwar
         >>>
         >>> def handler(event, context):
                 logger.info("Hello")
+                :param service:
+                :param level:
+                :param sampling_rate:
 
     """
     service = os.getenv("POWERTOOLS_SERVICE_NAME") or service
+    sampling_rate = os.getenv("POWERTOOLS_SAMPLE_RATE") or sampling_rate
     log_level = os.getenv("LOG_LEVEL") or level
     logger = logging.getLogger(name=service)
+
+    # sampling a small percentage of requests with debug level, using a float value 0.1 = 10%~
+
+    try:
+        if sampling_rate and random.random() <= float(sampling_rate):
+            log_level = logging.DEBUG
+    except ValueError:
+        logger.debug("POWERTOOLS_SAMPLE_RATE provided value {0} is not valid.".format(sampling_rate))
+
     logger.setLevel(log_level)
 
     # Patch logger by structuring its outputs as JSON
-    aws_lambda_logging.setup(level=log_level, service=service, **kwargs)
+    aws_lambda_logging.setup(
+        level=log_level, service=service, sampling_rate=sampling_rate, **kwargs
+    )
 
     return logger
 
 
 def logger_inject_lambda_context(
-    lambda_handler: Callable[[Dict, Any], Any] = None, log_event: bool = False
+        lambda_handler: Callable[[Dict, Any], Any] = None, log_event: bool = False
 ):
     """Decorator to capture Lambda contextual info and inject into struct logging
 
@@ -110,6 +132,8 @@ def logger_inject_lambda_context(
     -------
     decorate : Callable
         Decorated lambda handler
+        :param log_event:
+        :param lambda_handler:
     """
 
     # If handler is None we've been called with parameters
@@ -159,12 +183,12 @@ def __is_cold_start() -> str:
 
 
 def log_metric(
-    name: str,
-    namespace: str,
-    unit: MetricUnit,
-    value: float = 0,
-    service: str = "service_undefined",
-    **dimensions,
+        name: str,
+        namespace: str,
+        unit: MetricUnit,
+        value: float = 0,
+        service: str = "service_undefined",
+        **dimensions,
 ):
     """Logs a custom metric in a statsD-esque format to stdout.
 

python/tests/functional/test_logger.py

@@ -80,6 +80,19 @@ def test_setup_service_env_var(monkeypatch, root_logger, stdout):
     assert service_name == log["service"]
 
 
+def test_setup_sampling_rate(monkeypatch, root_logger, stdout):
+    # GIVEN samping rate is explicitly defined via POWERTOOLS_SAMPLE_RATE env
+    # WHEN logger is setup
+    # THEN sampling rate should be equals POWERTOOLS_SAMPLE_RATE value
+    sampling_rate = "0.1"
+    monkeypatch.setenv("POWERTOOLS_SAMPLE_RATE", sampling_rate)
+
+    logger = logger_setup()
+    logger.info("Hello")
+    log = json.loads(stdout.getvalue())
+    assert sampling_rate == log["sampling_rate"]
+
+
 def test_inject_lambda_context(root_logger, stdout, lambda_context):
     # GIVEN a lambda function is decorated with logger
     # WHEN logger is setup
@@ -128,9 +141,8 @@ def handler(event, context):
 
 
 def test_inject_lambda_context_log_event_request_env_var(
-    monkeypatch, root_logger, stdout, lambda_context
+        monkeypatch, root_logger, stdout, lambda_context
 ):
-
     # GIVEN a lambda function is decorated with logger instructed to log event
     # via POWERTOOLS_LOGGER_LOG_EVENT env
     # WHEN logger is setup
@@ -160,7 +172,7 @@ def handler(event, context):
 
 
 def test_inject_lambda_context_log_no_request_by_default(
-    monkeypatch, root_logger, stdout, lambda_context
+        monkeypatch, root_logger, stdout, lambda_context
 ):
     # GIVEN a lambda function is decorated with logger
     # WHEN logger is setup
@@ -281,12 +293,12 @@ def test_log_metric_multiple_dimensions(capsys):
     "invalid_input,expected",
     [
         (
-            {"unit": "seconds"},
-            "MONITORING|0|Seconds|test_metric|DemoApp|service=service_undefined\n",
+                {"unit": "seconds"},
+                "MONITORING|0|Seconds|test_metric|DemoApp|service=service_undefined\n",
         ),
         (
-            {"unit": "Seconds", "customer": None, "charge_id": "123", "payment_status": ""},
-            "MONITORING|0|Seconds|test_metric|DemoApp|service=service_undefined,charge_id=123\n",
+                {"unit": "Seconds", "customer": None, "charge_id": "123", "payment_status": ""},
+                "MONITORING|0|Seconds|test_metric|DemoApp|service=service_undefined,charge_id=123\n",
         ),
     ],
     ids=["metric unit as string lower case", "empty dimension value"],