docs(event_handler): demonstrate how to combine logger correlation ID and middleware (aws-powertools#3064)

* fix(parameters): make cache aware of single vs multiple calls

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

* chore: cleanup, add test for single and nested

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

* docs(event_handler): use correct correlation_id in logger.set_correlation_id example

* docs(event_handler): combine correlation id with logger for a more powerful example

* fix(parameters): make cache aware of single vs multiple calls

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

* chore: cleanup, add test for single and nested

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

* docs: remove Logger dependency on retrieval to address Simon's feedback

* docs: fix racing condition, more notes based on Simon's feedback

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

---------

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

Author: heitorlessa

docs/core/event_handler/api_gateway.md

@@ -406,10 +406,12 @@ Here's a sample middleware that extracts and injects correlation ID, using `APIG
     ```
 
     1. You can access current request like you normally would.
-    2. [Shared context is available](#sharing-contextual-data) to any middleware, Router and App instances.
-    3. Get response from the next middleware (if any) or from `/todos` route.
-    4. You can manipulate headers, body, or status code before returning it.
-    5. Register one or more middlewares in order of execution.
+    2. Logger extracts it first in the request path, so we can use it. <br><br> If this was available before, we'd use `app.context.get("correlation_id")`.
+    3. [Shared context is available](#sharing-contextual-data) to any middleware, Router and App instances. <br><br> For example, another middleware can now use `app.context.get("correlation_id")` to retrieve it.
+    4. Get response from the next middleware (if any) or from `/todos` route.
+    5. You can manipulate headers, body, or status code before returning it.
+    6. Register one or more middlewares in order of execution.
+    7. Logger extracts correlation ID from header and makes it available under `correlation_id` key, and `get_correlation_id()` method.
 
 === "middleware_getting_started_output.json"
 

examples/event_handler_rest/src/middleware_getting_started.py

@@ -12,21 +12,21 @@ def inject_correlation_id(app: APIGatewayRestResolver, next_middleware: NextMidd
     request_id = app.current_event.request_context.request_id  # (1)!
 
     # Use API Gateway REST API request ID if caller didn't include a correlation ID
-    correlation_id = app.current_event.headers.get("x-correlation-id", request_id)
+    correlation_id = logger.get_correlation_id() or request_id  # (2)!
 
     # Inject correlation ID in shared context and Logger
-    app.append_context(correlation_id=correlation_id)  # (2)!
+    app.append_context(correlation_id=correlation_id)  # (3)!
     logger.set_correlation_id(correlation_id)
 
     # Get response from next middleware OR /todos route
-    result = next_middleware(app)  # (3)!
+    result = next_middleware(app)  # (4)!
 
     # Include Correlation ID in the response back to caller
-    result.headers["x-correlation-id"] = correlation_id  # (4)!
+    result.headers["x-correlation-id"] = correlation_id  # (5)!
     return result
 
 
-@app.get("/todos", middlewares=[inject_correlation_id])  # (5)!
+@app.get("/todos", middlewares=[inject_correlation_id])  # (6)!
 def get_todos():
     todos: Response = requests.get("https://jsonplaceholder.typicode.com/todos")
     todos.raise_for_status()
@@ -35,6 +35,6 @@ def get_todos():
     return {"todos": todos.json()[:10]}
 
 
-@logger.inject_lambda_context
+@logger.inject_lambda_context(correlation_id_path='headers."x-correlation-id"')  # (7)!
 def lambda_handler(event, context):
     return app.resolve(event, context)

examples/event_handler_rest/src/middleware_global_middlewares_module.py

@@ -18,7 +18,7 @@ def inject_correlation_id(app: APIGatewayRestResolver, next_middleware: NextMidd
     request_id = app.current_event.request_context.request_id
 
     # Use API Gateway REST API request ID if caller didn't include a correlation ID
-    correlation_id = app.current_event.headers.get("x-correlation-id", request_id)
+    correlation_id = logger.get_correlation_id() or request_id  # elsewhere becomes app.context.get("correlation_id")
 
     # Inject correlation ID in shared context and Logger
     app.append_context(correlation_id=correlation_id)