docs: new section "Migrating from other Loggers" (#148)

* chore: fix typo in test comment

* chore: fix typo in metrics

* improv: add section to answer common migration questions

Signed-off-by: heitorlessa <[email protected]>

Author: heitorlessa

docs/content/core/logger.mdx

@@ -90,7 +90,7 @@ Key | Type | Example
 **function_request_id**| str | "899856cb-83d1-40d7-8611-9e78f15f32f4"
 
 <details>
-<summary><strong>Exerpt output in CloudWatch Logs</strong></summary>
+<summary><strong>Excerpt output in CloudWatch Logs</strong></summary>
 
 ```json:title=cloudwatch_logs.json
 {
@@ -164,9 +164,9 @@ def handler(event, context):
 ```
 
 <details>
-<summary><strong>Exerpt output in CloudWatch Logs</strong></summary>
+<summary><strong>Excerpt output in CloudWatch Logs</strong></summary>
 
-```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):
 ```
 
 <details>
-<summary><strong>Exerpt output in CloudWatch Logs</strong></summary>
+<summary><strong>Excerpt output in CloudWatch Logs</strong></summary>
 
 ```json:title=cloudwatch_logs.json
 {
@@ -260,3 +260,100 @@ def handler(event, context):
 }
 ```
 </details>
+
+
+## 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
+```
+
+<details>
+<summary><strong>Excerpt output in CloudWatch Logs</strong></summary>
+
+```json:title=cloudwatch_logs.json
+{
+   "level": "ERROR",
+   "location": "<module>: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 \"<input>\", line 2, in <module>\nValueError: something went wrong"
+}
+```
+</details>

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.
 
 <details>
-<summary><strong>Exerpt output in CloudWatch Logs</strong></summary>
+<summary><strong>Excerpt output in CloudWatch Logs</strong></summary>
 
 ```json:title=cloudwatch_logs.json
 {

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