fix(logger): force Logger to use local timezone when UTC flag is not set

aws_lambda_powertools/logging/formatter.py

@@ -144,6 +144,8 @@ def __init__(
 
         if self.utc:
             self.converter = time.gmtime
+        else:
+            self.converter = time.localtime
 
         self.keys_combined = {**self._build_default_keys(), **kwargs}
         self.log_format.update(**self.keys_combined)

docs/core/logger.md

@@ -39,7 +39,7 @@ Your Logger will include the following keys to your structured logging:
 | **level**: `str`           | `INFO`                                | Logging level                                                                                                                        |
 | **location**: `str`        | `collect.handler:1`                   | Source code location where statement was executed                                                                                    |
 | **message**: `Any`         | `Collecting payment`                  | Unserializable JSON values are casted as `str`                                                                                       |
-| **timestamp**: `str`       | `2021-05-03 10:20:19,650+0200`        | Timestamp with milliseconds, by default uses local timezone                                                                          |
+| **timestamp**: `str`       | `2021-05-03 10:20:19,650+0000`        | Timestamp with milliseconds, by default uses default lambda timezone (UTC)                                                                         |
 | **service**: `str`         | `payment`                             | Service name defined, by default `service_undefined`                                                                                 |
 | **xray_trace_id**: `str`   | `1-5759e988-bd862e3fe1be46a994272793` | When [tracing is enabled](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html){target="_blank"}, it shows X-Ray Trace ID |
 | **sampling_rate**: `float` | `0.1`                                 | When enabled, it shows sampling rate in percentage e.g. 10%                                                                          |
@@ -567,17 +567,24 @@ You can change the order of [standard Logger keys](#standard-structured-keys) or
     --8<-- "examples/logger/src/reordering_log_keys_output.json"
     ```
 
-#### Setting timestamp to UTC
+#### Setting timestamp to custom Timezone
 
-By default, this Logger and standard logging library emits records using local time timestamp. You can override this behavior via `utc` parameter:
+By default, this Logger and standard logging library emits records using default lambda time(UTC) timestamp. You can enforce this behavior via `utc` parameter.
 
-=== "setting_utc_timestamp.py"
+However, if you want to use your preferred timezone to format your log instead, you can use the timezone environment variable `TZ`: Either set it as Lambda Environment Variable. Or setup this value directly in your Lambda Hander.
 
-    ```python hl_lines="6"
+???+ tip
+    `TZ` environment variable will be ingnored if `utc` is set to `True`
+
+=== "setting_custom_timezone.py"
+
+    ```python hl_lines="9 12"
     --8<-- "examples/logger/src/setting_utc_timestamp.py"
     ```
 
-=== "setting_utc_timestamp_output.json"
+    1.  if you set TZ in lambda runtime, time.tzset() need to be called. You don't need it when setting TZ in lambda environment variable
+
+=== "setting_custom_timezone_output.json"
 
     ```json hl_lines="6 13"
     --8<-- "examples/logger/src/setting_utc_timestamp_output.json"

examples/logger/src/setting_utc_timestamp.py

@@ -1,7 +1,13 @@
+import os
+import time
+
 from aws_lambda_powertools import Logger
 
-logger = Logger(service="payment")
-logger.info("Local time")
+logger = Logger(service="payment", utc=True)
+logger.info("utf time")
+
+os.environ["TZ"] = "US/Eastern"
+time.tzset()  # (1)!
 
-logger_in_utc = Logger(service="order", utc=True)
-logger_in_utc.info("GMT time zone")
+logger_in_utc = Logger(service="order")
+logger_in_utc.info("US eastern time")

examples/logger/src/setting_utc_timestamp_output.json

@@ -1,16 +1,16 @@
 [
     {
-        "level": "INFO",
-        "location": "<module>:4",
-        "message": "Local time",
-        "timestamp": "2022-06-24 11:39:49,421+0200",
-        "service": "payment"
+        "level":"INFO",
+        "location":"<module>:6",
+        "message":"utf time",
+        "timestamp":"2023-10-06 02:46:54,097+0000",
+        "service":"payment"
     },
     {
-        "level": "INFO",
-        "location": "<module>:7",
-        "message": "GMT time zone",
-        "timestamp": "2022-06-24 09:39:49,421+0100",
-        "service": "order"
+        "level":"INFO",
+        "location":"<module>:12",
+        "message":"US eastern time",
+        "timestamp":"2023-10-05 22:46:54,097-0400",
+        "service":"order"
     }
 ]

package.json

@@ -1,9 +1,6 @@
 {
   "name": "aws-lambda-powertools-python-e2e",
   "version": "1.0.0",
-  "devDependencies": {
-    "aws-cdk": "^2.99.1"
-  },
   "dependencies": {
     "package-lock.json": "^1.0.0"
   }

tests/e2e/logger/handlers/tz_handler.py

@@ -0,0 +1,21 @@
+import os
+import time
+
+from aws_lambda_powertools import Logger
+
+
+def lambda_handler(event, context):
+    utc, datefmt, tz = event.get("utc", False), event.get("datefmt", None), event.get("tz", None)
+    if tz:
+        os.environ["TZ"] = tz
+        time.tzset()
+
+    logger = Logger(service=f"{utc}-{datefmt}-{tz}", utc=utc, datefmt=datefmt)
+    if logger.handlers[0].formatter.converter == time.localtime:
+        loggerType = "localtime_converter"
+    elif logger.handlers[0].formatter.converter == time.gmtime:
+        loggerType = "gmtime_converter"
+    else:
+        loggerType = "unknown"
+    logger.info(loggerType)
+    return "success"

tests/e2e/logger/test_logger.py

@@ -1,4 +1,6 @@
 import json
+import os
+import time
 from uuid import uuid4
 
 import pytest
@@ -17,6 +19,16 @@ def basic_handler_fn_arn(infrastructure: dict) -> str:
     return infrastructure.get("BasicHandlerArn", "")
 
 
+@pytest.fixture
+def tz_handler_fn(infrastructure: dict) -> str:
+    return infrastructure.get("TzHandler", "")
+
+
+@pytest.fixture
+def tz_handler_fn_arn(infrastructure: dict) -> str:
+    return infrastructure.get("TzHandlerArn", "")
+
+
 @pytest.mark.xdist_group(name="logger")
 def test_basic_lambda_logs_visible(basic_handler_fn, basic_handler_fn_arn):
     # GIVEN
@@ -36,3 +48,47 @@ def test_basic_lambda_logs_visible(basic_handler_fn, basic_handler_fn_arn):
     assert len(logs.get_cold_start_log()) == 1
     assert len(logs.get_log(key=custom_key)) == 2
     assert logs.have_keys(*LOGGER_LAMBDA_CONTEXT_KEYS) is True
+
+
+# test on combination of utc,tz,datefmt params
+@pytest.mark.xdist_group(name="logger")
+@pytest.mark.parametrize("utc", [False, True])
+@pytest.mark.parametrize("tz", ["US/Eastern", "UTC", "Asia/Shanghai"])
+@pytest.mark.parametrize("datefmt", ["%z", None])
+def test_lambda_tz(tz_handler_fn, tz_handler_fn_arn, utc, tz, datefmt):
+    # GIVEN
+    payload = json.dumps({"utc": utc, "tz": tz, "datefmt": datefmt})
+
+    # WHEN
+    _, execution_time = data_fetcher.get_lambda_response(lambda_arn=tz_handler_fn_arn, payload=payload)
+    data_fetcher.get_lambda_response(lambda_arn=tz_handler_fn_arn, payload=payload)
+
+    # THEN
+    logs = data_fetcher.get_logs(
+        function_name=tz_handler_fn,
+        start_time=execution_time,
+        minimum_log_entries=1,
+        filter_expression='{ $.service = "' + f"{utc}-{datefmt}-{tz}" + '" }',
+    )
+    result_list = logs.logs
+
+    assert len(result_list) > 0
+    result = result_list[0]
+
+    # When UTC
+    if utc:
+        # then use gmt converter
+        assert result.message == "gmtime_converter"
+    # When not UTC
+    else:
+        # then use local time converter
+        assert result.message == "localtime_converter"
+
+    if utc:
+        assert result.timestamp[-5:] == "+0000"
+    else:
+        os.environ["TZ"] = tz
+        time.tzset()
+        assert result.timestamp[-5:] == time.strftime("%z", time.localtime())
+
+    print(result)

tests/functional/test_logger_powertools_formatter.py

@@ -294,6 +294,14 @@ def test_log_in_utc(service_name):
     assert logger._logger.handlers[0].formatter.converter == time.gmtime
 
 
+def test_log_wo_utc(service_name):
+    # GIVEN a logger where UTC is false
+    logger = Logger(service=service_name, utc=False)
+
+    # THEN logging formatter time converter should use localtime fn
+    assert logger._logger.handlers[0].formatter.converter == time.localtime
+
+
 @pytest.mark.parametrize("message", ["hello", 1.10, {}, [], True, object()])
 def test_logging_various_primitives(stdout, service_name, message):
     # GIVEN a logger with default settings