diff --git a/CHANGELOG.md b/CHANGELOG.md index 78e82c3..1364394 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,11 @@ exception handler writes for a refused or invalid request, so a value added from a dependency never reached them. Call `set_context()` from the dependency instead, without a block. +- `ACCESS_REQUEST` routes a new field, `status_code_missing`. A catalogue that + declares its own `ACCESS_REQUEST` with an allow-list adds + `status_code_missing` to it. Otherwise the field is dropped, and with + `strict_fields=True` logging the access record of a request whose handler + raised fails. ### Added @@ -80,6 +85,11 @@ - Access records now follow the catalogue's routing for `ACCESS_REQUEST`. The app stream let every record from the access logger through by name, so an `ACCESS_REQUEST` routed away from the app stream still reached it. +- The access record for a request whose handler raised now carries + `status_code` 500, the status Starlette answers it with, instead of `null`, + and a `status_code_missing` message saying so. The middleware never sees + that response, so a handler registered for `Exception` or a middleware added + after this one can answer with another status than the record says. ## 0.7.0 - 2026-11-02 diff --git a/docs/STARTING_GUIDE.md b/docs/STARTING_GUIDE.md index 71be6c5..5494f35 100644 --- a/docs/STARTING_GUIDE.md +++ b/docs/STARTING_GUIDE.md @@ -327,6 +327,17 @@ the application. Added before `configure()`, it has nothing to read and says so: RuntimeError: access logging setting unknown: call gfmodules.logging.configure() before adding the middleware ``` +**Add it last, so it runs outermost.** If an unhandled exception reaches the +middleware, it never sees a response. The access record therefore uses +`status_code` 500, Starlette's default for unhandled exceptions, and includes a +`status_code_missing` message explaining the fallback. + +The recorded status may differ from the status actually sent if something +outside the middleware handles the exception. This can happen with middleware +added later or a handler registered for `Exception` or `500`. Handlers +registered for more specific exception classes run inside the middleware, so +their response status is recorded as sent. + **Request bodies are not logged unless you ask.** A body is the likeliest place for the data an application least wants in its logs, and the console handler applies no per-stream allow-list, so anything captured reaches stdout in full. diff --git a/examples/fastapi_app/events.md b/examples/fastapi_app/events.md index a525aff..013cdbe 100644 --- a/examples/fastapi_app/events.md +++ b/examples/fastapi_app/events.md @@ -40,7 +40,7 @@ The request context also holds these, but an event carries them only on the stre | `RESOURCE_DELETED` | 100701 | INFO | `resource_id`, `reason` | | `LOOKUP_REJECTED` | 100702 | WARNING | `resource_id`, `error_reason` | | `LOOKUP_MALFORMED` | 100702 | WARNING | `resource_id`, `error_reason` | -| `ACCESS_REQUEST` | 100 | INFO | `endpoint`, `method`, `status_code`, `duration_ms`, `body`, `body_truncated`, `caller_id` | +| `ACCESS_REQUEST` | 100 | INFO | `endpoint`, `method`, `status_code`, `status_code_missing`, `duration_ms`, `body`, `body_truncated`, `caller_id` | ## Stream `siem` diff --git a/gfmodules/logging/events.py b/gfmodules/logging/events.py index 1744422..08d6b25 100644 --- a/gfmodules/logging/events.py +++ b/gfmodules/logging/events.py @@ -285,7 +285,7 @@ class Log(DefaultEventCatalogue): "100", logging.INFO, (_APP,), - {_APP: ("endpoint", "method", "status_code", "duration_ms", "body", "body_truncated")}, + {_APP: ("endpoint", "method", "status_code", "status_code_missing", "duration_ms", "body", "body_truncated")}, ) diff --git a/gfmodules/logging/middleware.py b/gfmodules/logging/middleware.py index e3c39e7..d28f446 100644 --- a/gfmodules/logging/middleware.py +++ b/gfmodules/logging/middleware.py @@ -8,6 +8,7 @@ from contextlib import contextmanager from dataclasses import dataclass from functools import wraps +from http import HTTPStatus from types import MappingProxyType from typing import Any, TypeVar, cast @@ -265,9 +266,25 @@ def _log_access( start: float, ) -> None: fields: dict[str, Any] = { - "status_code": response.status_code if response is not None else None, + "status_code": response.status_code if response is not None else HTTPStatus.INTERNAL_SERVER_ERROR.value, "duration_ms": round((time.perf_counter() - start) * 1000), } + if response is None: + # Starlette builds the stack from the outside in: + # ServerErrorMiddleware -> user middlewares -> ExceptionMiddleware -> router + # ExceptionMiddleware turns an HTTPException, or an exception the app + # registered a handler for (other than Exception or 500), into a + # response before it gets back here. + # Any other exception gets back here as an exception: call_next + # raises, and there is no response to read the status code from. + # ServerErrorMiddleware turns it into a response, but only after this + # middleware has logged. By default it answers 500. A handler + # registered for Exception or 500, or a middleware added after this + # one, can answer with another status instead. + # So the 500 logged here is a guess, and the message says so. + fields["status_code_missing"] = ( + f"No response to read the status code from, logging it as {fields['status_code']}" + ) if body is not None: text, truncated = body # A truncated body is no longer parseable, so it stays a string. diff --git a/tests/test_middleware.py b/tests/test_middleware.py index f21e4db..1ba7eec 100644 --- a/tests/test_middleware.py +++ b/tests/test_middleware.py @@ -364,6 +364,7 @@ def test_the_access_record_carries_the_outcome(self, client: TestClient, records assert record.status_code == 200 # type: ignore[attr-defined] assert record.duration_ms >= 0 # type: ignore[attr-defined] assert record.name == "app.access" + assert not hasattr(record, "status_code_missing") def test_uses_the_route_specific_event_id_when_the_catalogue_maps_one( self, client: TestClient, records: RecordingHandler @@ -379,10 +380,14 @@ def test_falls_back_to_the_generic_access_event_id_for_unmapped_routes( assert records.with_event_id(ACCESS_EVENT_ID) - def test_still_logs_when_the_handler_raised(self, client: TestClient, records: RecordingHandler) -> None: - client.get("/boom") + def test_logs_the_500_the_client_gets_when_the_handler_raised( + self, client: TestClient, records: RecordingHandler + ) -> None: + assert client.get("/boom").status_code == 500 - assert records.with_event_id(ACCESS_EVENT_ID)[0].status_code is None # type: ignore[attr-defined] + record = records.with_event_id(ACCESS_EVENT_ID)[0] + assert record.status_code == 500 # type: ignore[attr-defined] + assert record.status_code_missing == "No response to read the status code from, logging it as 500" # type: ignore[attr-defined] def test_logs_nothing_when_the_configuration_leaves_access_logs_off( self, catalogue: type[CompleteCatalogue], records: RecordingHandler