Skip to content

Commit 92beb07

Browse files
heitorlessaheitorlessa
committed
docs: surface usage of new correlation_id and paths
1 parent 16a6ffc commit 92beb07

File tree

1 file changed

+199
-50
lines changed

1 file changed

+199
-50
lines changed

‎docs/core/logger.md

Lines changed: 199 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,89 @@ When debugging in non-production environments, you can instruct Logger to log th
143143
...
144144
```
145145

146+
#### Setting a Correlation ID
147+
148+
> New in 1.12.0
149+
150+
You can set a Correlation ID using `correlation_id_path` param by passing a [JMESPath expression](https://jmespath.org/tutorial.html){target="_blank"}.
151+
152+
=== "collect.py"
153+
154+
```python hl_lines="6"
155+
from aws_lambda_powertools import Logger
156+
157+
logger = Logger()
158+
159+
@logger.inject_lambda_context(correlation_id_path="headers.my_request_id_header")
160+
def handler(event, context):
161+
logger.info("Collecting payment")
162+
...
163+
```
164+
165+
=== "Example Event"
166+
167+
```json hl_lines="3"
168+
{
169+
"headers": {
170+
"my_request_id_header": "correlation_id_value"
171+
}
172+
}
173+
```
174+
175+
=== "Example CloudWatch Logs excerpt"
176+
177+
```json hl_lines="7"
178+
{
179+
"timestamp": "2020-05-24 18:17:33,774",
180+
"level": "INFO",
181+
"location": "collect.handler:1",
182+
"service": "payment",
183+
"sampling_rate": 0.0,
184+
"correlation_id": "correlation_id_value",
185+
"message": "Collecting payment"
186+
}
187+
```
188+
189+
We provide [built-in JMESPath expressions](#built-in-correlation-id-expressions) for known event sources, where either a request ID or X-Ray Trace ID are present.
190+
191+
=== "collect.py"
192+
193+
```python hl_lines="2"
194+
from aws_lambda_powertools import Logger
195+
from aws_lambda_powertools.logging import correlation_paths
196+
197+
logger = Logger()
198+
199+
@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)
200+
def handler(event, context):
201+
logger.info("Collecting payment")
202+
...
203+
```
204+
205+
=== "Example Event"
206+
207+
```json hl_lines="3"
208+
{
209+
"requestContext": {
210+
"requestId": "correlation_id_value"
211+
}
212+
}
213+
```
214+
215+
=== "Example CloudWatch Logs excerpt"
216+
217+
```json hl_lines="7"
218+
{
219+
"timestamp": "2020-05-24 18:17:33,774",
220+
"level": "INFO",
221+
"location": "collect.handler:1",
222+
"service": "payment",
223+
"sampling_rate": 0.0,
224+
"correlation_id": "correlation_id_value",
225+
"message": "Collecting payment"
226+
}
227+
```
228+
146229
### Appending additional keys
147230

148231
You can append additional keys using either mechanism:
@@ -188,24 +271,58 @@ You can append your own keys to your existing Logger via `structure_logs(append=
188271

189272
This example will add `order_id` if its value is not empty, and in subsequent invocations where `order_id` might not be present it'll remove it from the logger.
190273

191-
#### Setting correlation ID
274+
#### extra parameter
192275

193-
You can set a correlation_id to your existing Logger via `set_correlation_id(value)` method.
276+
> New in 1.10.0
277+
278+
Extra parameter is available for all log levels' methods, as implemented in the standard logging library - e.g. `logger.info, logger.warning`.
279+
280+
It accepts any dictionary, and all keyword arguments will be added as part of the root structure of the logs for that log statement.
281+
282+
!!! info "Any keyword argument added using `extra` will not be persisted for subsequent messages."
283+
284+
=== "extra_parameter.py"
285+
286+
```python hl_lines="6"
287+
logger = Logger(service="payment")
288+
289+
fields = { "request_id": "1123" }
290+
291+
logger.info("Hello", extra=fields)
292+
```
293+
=== "Example CloudWatch Logs excerpt"
294+
295+
```json hl_lines="7"
296+
{
297+
"timestamp": "2021-01-12 14:08:12,357",
298+
"level": "INFO",
299+
"location": "collect.handler:1",
300+
"service": "payment",
301+
"sampling_rate": 0.0,
302+
"request_id": "1123",
303+
"message": "Collecting payment"
304+
}
305+
```
306+
307+
#### set_correlation_id method
308+
309+
> New in 1.12.0
310+
311+
You can set a correlation_id to your existing Logger via `set_correlation_id(value)` method by passing any string value.
194312

195313
=== "collect.py"
196314

197-
```python hl_lines="8"
315+
```python hl_lines="6"
198316
from aws_lambda_powertools import Logger
199-
from aws_lambda_powertools.utilities.data_classes import APIGatewayProxyEvent
200317

201318
logger = Logger()
202319

203320
def handler(event, context):
204-
event = APIGatewayProxyEvent(event)
205-
logger.set_correlation_id(event.request_context.request_id)
321+
logger.set_correlation_id(event["requestContext"]["requestId"])
206322
logger.info("Collecting payment")
207323
...
208324
```
325+
209326
=== "Example Event"
210327

211328
```json hl_lines="3"
@@ -215,6 +332,7 @@ You can set a correlation_id to your existing Logger via `set_correlation_id(val
215332
}
216333
}
217334
```
335+
218336
=== "Example CloudWatch Logs excerpt"
219337

220338
```json hl_lines="7"
@@ -229,37 +347,82 @@ You can set a correlation_id to your existing Logger via `set_correlation_id(val
229347
}
230348
```
231349

232-
#### extra parameter
233-
234-
Extra parameter is available for all log levels' methods, as implemented in the standard logging library - e.g. `logger.info, logger.warning`.
350+
Alternatively, you can combine [Data Classes utility](../utilities/data_classes.md) with Logger to use dot notation object:
235351

236-
It accepts any dictionary, and all keyword arguments will be added as part of the root structure of the logs for that log statement.
352+
=== "collect.py"
237353

238-
!!! info "Any keyword argument added using `extra` will not be persisted for subsequent messages."
354+
```python hl_lines="2 7-8"
355+
from aws_lambda_powertools import Logger
356+
from aws_lambda_powertools.utilities.data_classes import APIGatewayProxyEvent
239357

240-
=== "extra_parameter.py"
358+
logger = Logger()
241359

242-
```python hl_lines="6"
243-
logger = Logger(service="payment")
360+
def handler(event, context):
361+
event = APIGatewayProxyEvent(event)
362+
logger.set_correlation_id(event.request_context.request_id)
363+
logger.info("Collecting payment")
364+
...
365+
```
366+
=== "Example Event"
244367

245-
fields = { "request_id": "1123" }
368+
```json hl_lines="3"
369+
{
370+
"requestContext": {
371+
"requestId": "correlation_id_value"
372+
}
373+
}
374+
```
246375

247-
logger.info("Hello", extra=fields)
248-
```
249376
=== "Example CloudWatch Logs excerpt"
250377

251378
```json hl_lines="7"
252379
{
253-
"timestamp": "2021-01-12 14:08:12,357",
380+
"timestamp": "2020-05-24 18:17:33,774",
254381
"level": "INFO",
255382
"location": "collect.handler:1",
256383
"service": "payment",
257384
"sampling_rate": 0.0,
258-
"request_id": "1123",
385+
"correlation_id": "correlation_id_value",
259386
"message": "Collecting payment"
260387
}
261388
```
262389

390+
### Logging exceptions
391+
392+
When logging exceptions, Logger will add new keys named `exception_name` and `exception` with the full traceback as a string.
393+
394+
!!! tip
395+
> New in 1.12.0
396+
397+
You can use your preferred Log Analytics tool to enumerate exceptions across all your services using `exception_name` key.
398+
399+
=== "logging_an_exception.py"
400+
401+
```python hl_lines="7"
402+
from aws_lambda_powertools import Logger
403+
logger = Logger()
404+
405+
try:
406+
raise ValueError("something went wrong")
407+
except Exception:
408+
logger.exception("Received an exception")
409+
```
410+
411+
=== "Example CloudWatch Logs excerpt"
412+
413+
```json
414+
{
415+
"level": "ERROR",
416+
"location": "<module>:4",
417+
"message": "Received an exception",
418+
"timestamp": "2020-08-28 18:11:38,886",
419+
"service": "service_undefined",
420+
"sampling_rate": 0.0,
421+
"exception_name": "ValueError",
422+
"exception": "Traceback (most recent call last):\n File \"<input>\", line 2, in <module>\nValueError: something went wrong"
423+
}
424+
```
425+
263426
## Advanced
264427

265428
### Reusing Logger across your code
@@ -490,37 +653,6 @@ You can also change the order of the following log record keys via the `log_reco
490653
}
491654
```
492655

493-
#### Logging exceptions
494-
495-
When logging exceptions, Logger will add new keys named `exception_name` and `exception` with the full traceback as a string.
496-
497-
=== "logging_an_exception.py"
498-
499-
```python hl_lines="7"
500-
from aws_lambda_powertools import Logger
501-
logger = Logger()
502-
503-
try:
504-
raise ValueError("something went wrong")
505-
except Exception:
506-
logger.exception("Received an exception")
507-
```
508-
509-
=== "Example CloudWatch Logs excerpt"
510-
511-
```json
512-
{
513-
"level": "ERROR",
514-
"location": "<module>:4",
515-
"message": "Received an exception",
516-
"timestamp": "2020-08-28 18:11:38,886",
517-
"service": "service_undefined",
518-
"sampling_rate": 0.0,
519-
"exception_name": "ValueError",
520-
"exception": "Traceback (most recent call last):\n File \"<input>\", line 2, in <module>\nValueError: something went wrong"
521-
}
522-
```
523-
524656
## Testing your code
525657

526658
When unit testing your code that makes use of `inject_lambda_context` decorator, you need to pass a dummy Lambda Context, or else Logger will fail.
@@ -585,6 +717,23 @@ POWERTOOLS_LOG_DEDUPLICATION_DISABLED="1" pytest -o log_cli=1
585717
!!! warning
586718
This feature should be used with care, as it explicitly disables our ability to filter propagated messages to the root logger (if configured).
587719

720+
## Built-in Correlation ID expressions
721+
722+
> New in 1.12.0
723+
724+
You can use any of the following built-in JMESPath expressions as part of [inject_lambda_context decorator](#setting-a-correlation-id).
725+
726+
!!! note "Escaping necessary for the `-` character"
727+
Any object key named with `-` must be escaped, for example **`request.headers."x-amzn-trace-id"`**.
728+
729+
Name | Expression | Description
730+
------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------
731+
**API_GATEWAY_REST** | `"requestContext.requestId"` | API Gateway REST API request ID
732+
**API_GATEWAY_HTTP** | `"requestContext.requestId"` | API Gateway HTTP API request ID
733+
**APPSYNC_RESOLVER** | `'request.headers."x-amzn-trace-id"'` | AppSync X-Ray Trace ID
734+
**APPLICATION_LOAD_BALANCER** | `'headers."x-amzn-trace-id"'` | ALB X-Ray Trace ID
735+
**EVENT_BRIDGE** | `"id"` | EventBridge Event ID
736+
588737
## FAQ
589738

590739
**How can I enable boto3 and botocore library logging?**

0 commit comments

Comments
 (0)