Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
11 changes: 11 additions & 0 deletions docs/STARTING_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion examples/fastapi_app/events.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand Down
2 changes: 1 addition & 1 deletion gfmodules/logging/events.py
Original file line number Diff line number Diff line change
Expand Up @@ -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")},
)


Expand Down
19 changes: 18 additions & 1 deletion gfmodules/logging/middleware.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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,
Comment thread
ricklambrechts marked this conversation as resolved.
Resolved
"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.
Expand Down
11 changes: 8 additions & 3 deletions tests/test_middleware.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Comment thread
ricklambrechts marked this conversation as resolved.
Resolved

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
Expand Down
Loading