From 7505fcb0c38a9b74561606c72ad5352e6cd33e65 Mon Sep 17 00:00:00 2001 From: Kristoffer Bakkejord Date: Fri, 1 Jul 2022 09:34:30 +0200 Subject: [PATCH 1/6] docs(logger): document enriching logs with logrecord attributes --- docs/core/logger.md | 19 ++++++++++++++++++ .../logger/src/append_and_remove_keys.json | 20 +++++++++++++++++++ examples/logger/src/append_and_remove_keys.py | 12 +++++++++++ 3 files changed, 51 insertions(+) create mode 100644 examples/logger/src/append_and_remove_keys.json create mode 100644 examples/logger/src/append_and_remove_keys.py diff --git a/docs/core/logger.md b/docs/core/logger.md index 90353b060c4..05494ec03d7 100644 --- a/docs/core/logger.md +++ b/docs/core/logger.md @@ -604,6 +604,25 @@ By default all registered loggers will be modified. You can change this behavior ---8<-- "examples/logger/src/cloning_logger_config.py" ``` +**How can I add standard library logging attributes to a log record?** + +The Python standard library log records contains a [large set of atttributes](https://docs.python.org/3/library/logging.html#logrecord-attributes), however only a few are included in the powertools log record by default. + +If you need to add additional records, these can be included as `kwargs` to `Logger`, or to `LambdaPowertoolsFormatter` when they are being instantiated, or to managed later with the `append_keys` or `remove_keys` methods. + +=== "collect.py" + + ```python hl_lines="3 8 10" + ---8<-- "examples/logger/src/append_and_remove_keys.py" + ``` +=== "Example CloudWatch Logs excerpt" + + ```json hl_lines="6 15-16" + ---8<-- "examples/logger/src/append_and_remove_keys.json" + ``` + +For log records originating from powertools `Logger`, the `name` attribute will be the same as `service`, for log records coming from standard library logger, it will be the name of the logger (i.e. what was used as name argument to `logging.getLogger`). + **What's the difference between `append_keys` and `extra`?** Keys added with `append_keys` will persist across multiple log messages while keys added via `extra` will only be available in a given log message operation. diff --git a/examples/logger/src/append_and_remove_keys.json b/examples/logger/src/append_and_remove_keys.json new file mode 100644 index 00000000000..a058e32c4d1 --- /dev/null +++ b/examples/logger/src/append_and_remove_keys.json @@ -0,0 +1,20 @@ +[ + { + "level": "INFO", + "location": ":16", + "message": "Name should be equal service value", + "name": "payment", + "service": "payment", + "timestamp": "2022-07-01 07:09:46,330+0000" + }, + { + "level": "INFO", + "location": ":23", + "message": "This will include process ID and name", + "name": "payment", + "process": "9", + "processName": "MainProcess", + "service": "payment", + "timestamp": "2022-07-01 07:09:46,330+0000" + } +] diff --git a/examples/logger/src/append_and_remove_keys.py b/examples/logger/src/append_and_remove_keys.py new file mode 100644 index 00000000000..285b0312224 --- /dev/null +++ b/examples/logger/src/append_and_remove_keys.py @@ -0,0 +1,12 @@ +from aws_lambda_powertools import Logger + +logger = Logger(service="payment", name="%(name)s") + +logger.info("Name should be equal service value") + +additional_log_attributes = {"process": "%(process)d", "processName": "%(processName)s"} +logger.append_keys(**additional_log_attributes) +logger.info("This will include process ID and name") +logger.remove_keys(["processName"]) + +# further messages will not include processName From f2a24d2e3ec1dc4e1a63b6009cfcf99d31838d8e Mon Sep 17 00:00:00 2001 From: Kristoffer Bakkejord Date: Fri, 1 Jul 2022 13:41:08 +0200 Subject: [PATCH 2/6] docs(logger): write Powertools with Capitalization Co-authored-by: Heitor Lessa --- docs/core/logger.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/core/logger.md b/docs/core/logger.md index 05494ec03d7..b29ccfcd127 100644 --- a/docs/core/logger.md +++ b/docs/core/logger.md @@ -594,7 +594,7 @@ for the given name and level to the logging module. By default, this logs all bo ---8<-- "examples/logger/src/enabling_boto_logging.py" ``` -**How can I enable powertools logging for imported libraries?** +**How can I enable Powertools logging for imported libraries?** You can copy the Logger setup to all or sub-sets of registered external loggers. Use the `copy_config_to_registered_logger` method to do this. @@ -606,7 +606,7 @@ By default all registered loggers will be modified. You can change this behavior **How can I add standard library logging attributes to a log record?** -The Python standard library log records contains a [large set of atttributes](https://docs.python.org/3/library/logging.html#logrecord-attributes), however only a few are included in the powertools log record by default. +The Python standard library log records contains a [large set of atttributes](https://docs.python.org/3/library/logging.html#logrecord-attributes){target="_blank"}, however only a few are included in Powertools Logger log record by default. If you need to add additional records, these can be included as `kwargs` to `Logger`, or to `LambdaPowertoolsFormatter` when they are being instantiated, or to managed later with the `append_keys` or `remove_keys` methods. @@ -621,7 +621,7 @@ If you need to add additional records, these can be included as `kwargs` to `Log ---8<-- "examples/logger/src/append_and_remove_keys.json" ``` -For log records originating from powertools `Logger`, the `name` attribute will be the same as `service`, for log records coming from standard library logger, it will be the name of the logger (i.e. what was used as name argument to `logging.getLogger`). +For log records originating from Powertools `Logger`, the `name` attribute will be the same as `service`, for log records coming from standard library logger, it will be the name of the logger (i.e. what was used as name argument to `logging.getLogger`). **What's the difference between `append_keys` and `extra`?** From 3175731108e1c6cf2927734216b95d03feb1d843 Mon Sep 17 00:00:00 2001 From: Kristoffer Bakkejord Date: Fri, 1 Jul 2022 13:42:00 +0200 Subject: [PATCH 3/6] docs(logger): shorten sentences for readability Co-authored-by: Heitor Lessa --- docs/core/logger.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/core/logger.md b/docs/core/logger.md index b29ccfcd127..6e5ae30073b 100644 --- a/docs/core/logger.md +++ b/docs/core/logger.md @@ -608,7 +608,9 @@ By default all registered loggers will be modified. You can change this behavior The Python standard library log records contains a [large set of atttributes](https://docs.python.org/3/library/logging.html#logrecord-attributes){target="_blank"}, however only a few are included in Powertools Logger log record by default. -If you need to add additional records, these can be included as `kwargs` to `Logger`, or to `LambdaPowertoolsFormatter` when they are being instantiated, or to managed later with the `append_keys` or `remove_keys` methods. +You can include any of these logging attributes as key value arguments (`kwargs`) when instantiating `Logger` or `LambdaPowertoolsFormatter`. + +You can also add them later anywhere in your code with `append_keys`, or remove them with `remove_keys` methods. === "collect.py" From 3e5ba8418e9bc5fb0440aea04d988f93c28c1e8a Mon Sep 17 00:00:00 2001 From: Kristoffer Bakkejord Date: Fri, 1 Jul 2022 14:15:02 +0200 Subject: [PATCH 4/6] docs(logger): fix incorrect function name --- examples/logger/src/cloning_logger_config.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/logger/src/cloning_logger_config.py b/examples/logger/src/cloning_logger_config.py index 7472feee448..27075568ae9 100644 --- a/examples/logger/src/cloning_logger_config.py +++ b/examples/logger/src/cloning_logger_config.py @@ -5,7 +5,7 @@ logger = Logger() -external_logger = logging.logger() +external_logger = logging.getLogger() utils.copy_config_to_registered_loggers(source_logger=logger) external_logger.info("test message") From fe34e7a0ed32b51e68161b040d92eae34099d314 Mon Sep 17 00:00:00 2001 From: Kristoffer Bakkejord Date: Fri, 1 Jul 2022 14:24:07 +0200 Subject: [PATCH 5/6] docs(logger): Use headers for FAQ section --- docs/core/logger.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/core/logger.md b/docs/core/logger.md index 6e5ae30073b..38aa44006da 100644 --- a/docs/core/logger.md +++ b/docs/core/logger.md @@ -585,7 +585,7 @@ POWERTOOLS_LOG_DEDUPLICATION_DISABLED="1" pytest -o log_cli=1 ## FAQ -**How can I enable boto3 and botocore library logging?** +### How can I enable boto3 and botocore library logging? You can enable the `botocore` and `boto3` logs by using the `set_stream_logger` method, this method will add a stream handler for the given name and level to the logging module. By default, this logs all boto3 messages to stdout. @@ -594,7 +594,7 @@ for the given name and level to the logging module. By default, this logs all bo ---8<-- "examples/logger/src/enabling_boto_logging.py" ``` -**How can I enable Powertools logging for imported libraries?** +### How can I enable Powertools logging for imported libraries? You can copy the Logger setup to all or sub-sets of registered external loggers. Use the `copy_config_to_registered_logger` method to do this. @@ -604,7 +604,7 @@ By default all registered loggers will be modified. You can change this behavior ---8<-- "examples/logger/src/cloning_logger_config.py" ``` -**How can I add standard library logging attributes to a log record?** +### How can I add standard library logging attributes to a log record? The Python standard library log records contains a [large set of atttributes](https://docs.python.org/3/library/logging.html#logrecord-attributes){target="_blank"}, however only a few are included in Powertools Logger log record by default. @@ -625,7 +625,7 @@ You can also add them later anywhere in your code with `append_keys`, or remove For log records originating from Powertools `Logger`, the `name` attribute will be the same as `service`, for log records coming from standard library logger, it will be the name of the logger (i.e. what was used as name argument to `logging.getLogger`). -**What's the difference between `append_keys` and `extra`?** +### What's the difference between `append_keys` and `extra`? Keys added with `append_keys` will persist across multiple log messages while keys added via `extra` will only be available in a given log message operation. @@ -643,6 +643,6 @@ Here's an example where we persist `payment_id` not `request_id`. Note that `pay ---8<-- "examples/logger/src/append_keys_vs_extra_output.json" ``` -**How do I aggregate and search Powertools logs across accounts?** +### How do I aggregate and search Powertools logs across accounts? As of now, ElasticSearch (ELK) or 3rd party solutions are best suited to this task. Please refer to this [discussion for more details](https://github.com/awslabs/aws-lambda-powertools-python/issues/460) From abecfb56a484bd98bdf1b7e84b1fadada6521734 Mon Sep 17 00:00:00 2001 From: Kristoffer Bakkejord Date: Fri, 1 Jul 2022 15:13:27 +0200 Subject: [PATCH 6/6] docs(logger): be consistent in use of "Powertools Logger" Co-authored-by: Heitor Lessa --- docs/core/logger.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/logger.md b/docs/core/logger.md index 38aa44006da..23d57e251b9 100644 --- a/docs/core/logger.md +++ b/docs/core/logger.md @@ -623,7 +623,7 @@ You can also add them later anywhere in your code with `append_keys`, or remove ---8<-- "examples/logger/src/append_and_remove_keys.json" ``` -For log records originating from Powertools `Logger`, the `name` attribute will be the same as `service`, for log records coming from standard library logger, it will be the name of the logger (i.e. what was used as name argument to `logging.getLogger`). +For log records originating from Powertools Logger, the `name` attribute will be the same as `service`, for log records coming from standard library logger, it will be the name of the logger (i.e. what was used as name argument to `logging.getLogger`). ### What's the difference between `append_keys` and `extra`?