From d2aef1f4ace86bba1a5a807ca066789315ec594c Mon Sep 17 00:00:00 2001 From: thomas-samoht <54805624+thomas-samoht@users.noreply.github.com> Date: Mon, 2 Nov 2026 16:36:30 +0100 Subject: [PATCH 1/3] Log status 500 for a request whose handler raised Problem: when the handler raised, call_next() raised too and the access record was logged with status_code null. The client still received an answer, the 500 that Starlette's ServerErrorMiddleware sends for an unhandled exception, but the access record did not say so. Anything counting server errors on the app stream missed exactly the requests that crashed. Fix: the access record carries 500 when there is no response. The middleware is meant to be added last, so ServerErrorMiddleware is the only layer outside it, and that is the status it sends. An exception handler registered for Exception may answer with another status, which the middleware cannot see, as the exception leaves it before the handler runs. The test that pinned null now expects the 500 the client gets. --- CHANGELOG.md | 2 ++ gfmodules/logging/middleware.py | 3 ++- tests/test_middleware.py | 8 +++++--- 3 files changed, 9 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 78e82c3..e90939d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -80,6 +80,8 @@ - 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`. ## 0.7.0 - 2026-11-02 diff --git a/gfmodules/logging/middleware.py b/gfmodules/logging/middleware.py index e3c39e7..c001e9f 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,7 +266,7 @@ 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 body is not None: diff --git a/tests/test_middleware.py b/tests/test_middleware.py index f21e4db..216f753 100644 --- a/tests/test_middleware.py +++ b/tests/test_middleware.py @@ -379,10 +379,12 @@ 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] + assert records.with_event_id(ACCESS_EVENT_ID)[0].status_code == 500 # type: ignore[attr-defined] def test_logs_nothing_when_the_configuration_leaves_access_logs_off( self, catalogue: type[CompleteCatalogue], records: RecordingHandler From dfb330392a326596ebfffc848e28e482fda94f4a Mon Sep 17 00:00:00 2001 From: thomas-samoht <54805624+thomas-samoht@users.noreply.github.com> Date: Mon, 9 Nov 2026 14:34:54 +0100 Subject: [PATCH 2/3] Added comments clarifying the issue on a missing status code --- CHANGELOG.md | 10 +++++++++- docs/STARTING_GUIDE.md | 9 +++++++++ examples/fastapi_app/events.md | 2 +- gfmodules/logging/events.py | 2 +- gfmodules/logging/middleware.py | 16 ++++++++++++++++ tests/test_middleware.py | 5 ++++- 6 files changed, 40 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e90939d..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 @@ -81,7 +86,10 @@ 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`. + `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..c5302b4 100644 --- a/docs/STARTING_GUIDE.md +++ b/docs/STARTING_GUIDE.md @@ -327,6 +327,15 @@ 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.** When the handler raises, the middleware +never sees a response, so the access record carries `status_code` 500, the +status Starlette answers an unhandled exception with, and a +`status_code_missing` message saying so. That holds only while nothing outside the middleware answers instead. A +middleware added after it, or a handler registered for `Exception` or `500`, +may send another status than the record says. A handler registered for a more +specific exception class runs inside the middleware, so its 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 c001e9f..d28f446 100644 --- a/gfmodules/logging/middleware.py +++ b/gfmodules/logging/middleware.py @@ -269,6 +269,22 @@ def _log_access( "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 216f753..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 @@ -384,7 +385,9 @@ def test_logs_the_500_the_client_gets_when_the_handler_raised( ) -> None: assert client.get("/boom").status_code == 500 - assert records.with_event_id(ACCESS_EVENT_ID)[0].status_code == 500 # 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 From 72225ae43e6f24c4b54f5db40443c2f5ac201ed8 Mon Sep 17 00:00:00 2001 From: thomas-samoht <54805624+thomas-samoht@users.noreply.github.com> Date: Tue, 10 Nov 2026 10:03:02 +0100 Subject: [PATCH 3/3] Reword the missing status code section of the starting guide --- docs/STARTING_GUIDE.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/STARTING_GUIDE.md b/docs/STARTING_GUIDE.md index c5302b4..5494f35 100644 --- a/docs/STARTING_GUIDE.md +++ b/docs/STARTING_GUIDE.md @@ -327,14 +327,16 @@ 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.** When the handler raises, the middleware -never sees a response, so the access record carries `status_code` 500, the -status Starlette answers an unhandled exception with, and a -`status_code_missing` message saying so. That holds only while nothing outside the middleware answers instead. A -middleware added after it, or a handler registered for `Exception` or `500`, -may send another status than the record says. A handler registered for a more -specific exception class runs inside the middleware, so its status is recorded -as sent. +**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