diff --git a/docs/content/core/logger.mdx b/docs/content/core/logger.mdx index 3d435c4a116..7c977be4e97 100644 --- a/docs/content/core/logger.mdx +++ b/docs/content/core/logger.mdx @@ -90,7 +90,7 @@ Key | Type | Example **function_request_id**| str | "899856cb-83d1-40d7-8611-9e78f15f32f4"
-Exerpt output in CloudWatch Logs +Excerpt output in CloudWatch Logs ```json:title=cloudwatch_logs.json { @@ -164,9 +164,9 @@ def handler(event, context): ```
-Exerpt output in CloudWatch Logs +Excerpt output in CloudWatch Logs -```json:title=cloudwatch_logs.jsonn +```json:title=cloudwatch_logs.json { "timestamp": "2020-05-24 18:17:33,774", "level": "INFO", @@ -242,7 +242,7 @@ def handler(event, context): ```
-Exerpt output in CloudWatch Logs +Excerpt output in CloudWatch Logs ```json:title=cloudwatch_logs.json { @@ -260,3 +260,100 @@ def handler(event, context): } ```
+ + +## Migrating from other Loggers + +If you're migrating from other Loggers, there are few key points to be aware of: **Service parameter**, **Inheriting Loggers**, **Overriding Log records**, and **Logging exceptions**. + +### The service parameter + +Service is what defines what the function is responsible for, or part of (e.g payment service), and the name of the Logger. + +For Logger, the `service` is the logging key customers can use to search log operations for one or more functions - For example, **search for all errors, or messages like X, where service is payment**. + +### Inheriting Loggers + +> Python Logging hierarchy happens via the dot notation: `service`, `service.child`, `service.child_2`. + +For inheritance, Logger uses a `child=True` parameter along with `service` being the same value across Loggers. + +For child Loggers, we introspect the name of your module where `Logger(child=True, service="name")` is called, and we name your Logger as **{service}.{filename}**. + +A common issue when migrating from other Loggers is that `service` might be defined in the parent Logger (no child param), and not defined in the child Logger: + +```python:title=incorrect_logger_inheritance.py +# app.py +import my_module +from aws_lambda_powertools import Logger + +logger = Logger(service="payment") # highlight-line +... + +# my_module.py +from aws_lambda_powertools import Logger + +logger = Logger(child=True) # highlight-line +``` + +In this case, Logger will register a Logger named `payment`, and a Logger named `service_undefined`. The latter isn't inheriting from the parent, and will have no handler, thus no message being logged to standard output. + +This can be fixed by either ensuring both has the `service` value as `payment`, or simply use the environment variable `POWERTOOLS_SERVICE_NAME` to ensure service value will be the same across all Loggers when not explicitly set. + +### Overriding Log records + +You might want to continue to use the same date formatting style, or override `location` to display the `package.function_name:line_number` as you previously had. + +Logger allows you to either change the format or suppress the following keys altogether at the initialization: `location`, `timestamp`, `level`, and `datefmt` + +```python +from aws_lambda_powertools import Logger + +# override default values for location and timestamp format +logger = Logger(stream=stdout, location="[%(funcName)s] %(module)s", datefmt="fake-datefmt") # highlight-line + +# suppress location key +logger = Logger(stream=stdout, location=None) # highlight-line +``` + +Alternatively, you can also change the order of the following log record keys via the `log_record_order` parameter: `level`, location`, message`, and timestamp` + +```python +from aws_lambda_powertools import Logger + +# make message as the first key +logger = Logger(stream=stdout, log_record_order=["message"]) # highlight-line + +# Default key sorting order +logger = Logger(stream=stdout, log_record_order=["level","location","message","timestamp"]) # highlight-line +``` + +### Logging exceptions + +When logging exceptions, Logger will add a new key named `exception`, and will serialize the full traceback as a string. + +```python:title=logging_an_exception.py +from aws_lambda_powertools import Logger +logger = Logger() + +try: + raise ValueError("something went wrong") +except Exception: + logger.exception("Received an exception") # highlight-line +``` + +
+Excerpt output in CloudWatch Logs + +```json:title=cloudwatch_logs.json +{ + "level": "ERROR", + "location": ":4", + "message": "Received an exception", + "timestamp": "2020-08-28 18:11:38,886", + "service": "service_undefined", + "sampling_rate": 0.0, + "exception": "Traceback (most recent call last):\n File \"\", line 2, in \nValueError: something went wrong" +} +``` +
diff --git a/docs/content/core/metrics.mdx b/docs/content/core/metrics.mdx index 9b750c28622..be1b9feaa5b 100644 --- a/docs/content/core/metrics.mdx +++ b/docs/content/core/metrics.mdx @@ -113,7 +113,7 @@ metrics.add_metadata(key="booking_id", value="booking_uuid") # highlight-line This will be available in CloudWatch Logs to ease operations on high cardinal data.
-Exerpt output in CloudWatch Logs +Excerpt output in CloudWatch Logs ```json:title=cloudwatch_logs.json { diff --git a/tests/functional/test_aws_lambda_logging.py b/tests/functional/test_aws_lambda_logging.py index b633acca390..290090ebe8b 100644 --- a/tests/functional/test_aws_lambda_logging.py +++ b/tests/functional/test_aws_lambda_logging.py @@ -132,7 +132,7 @@ def test_log_dict_key_seq(stdout): def test_log_dict_key_custom_seq(stdout): - # GIVEN a logger configuration with format_keys set to ["message"] + # GIVEN a logger configuration with log_record_order set to ["message"] logger = Logger(stream=stdout, log_record_order=["message"]) # WHEN logging a message