Emit structured JSON logs to stdout #27

New issue

Open

opened 2026-04-19 11:08:23 -06:00 by claude-code · 0 comments

claude-code commented

2026-04-19 11:08:23 -06:00

Collaborator

Part of the platform-contract intake (#25).

Promtail on home-ctr-onyx auto-ships Docker stdout to Loki and extracts level + event as queryable labels when logs are JSON. The intake (5.1) commits to structured JSON at launch, not deferred.

Scope

App logs and uvicorn access logs must be JSON on stdout.
Each line must include level and event so Promtail indexes them as labels. Additional fields (request path, status, duration, etc.) are searchable via | json in LogQL but don't need to be labels.
Configuration applied via uvicorn's --log-config (YAML) + stdlib logging. No new runtime dependency if stdlib is enough; if we pull in a third-party JSON formatter it should be a small, well-maintained one (python-json-logger is the likely candidate).

Out of scope

structlog. The indexing contract only needs level + event; the full structlog pipeline is more than we need for a single-container app.
Log shipping config — Promtail on the host handles it.

Deliverables

Log config that produces JSON with level and event for both app and access logs.
Tests that verify the format (at minimum: parse one captured line as JSON, assert level and event keys).
Docs note: example LogQL queries for Quartermaster, mirroring the Archon contract's block.

Tracks work that blocks first deploy per #25.

Part of the platform-contract intake (#25). Promtail on `home-ctr-onyx` auto-ships Docker stdout to Loki and extracts `level` + `event` as queryable labels when logs are JSON. The intake (5.1) commits to structured JSON at launch, not deferred. ## Scope - App logs and uvicorn access logs must be JSON on stdout. - Each line must include `level` and `event` so Promtail indexes them as labels. Additional fields (request path, status, duration, etc.) are searchable via `| json` in LogQL but don't need to be labels. - Configuration applied via uvicorn's `--log-config` (YAML) + stdlib `logging`. No new runtime dependency if stdlib is enough; if we pull in a third-party JSON formatter it should be a small, well-maintained one (`python-json-logger` is the likely candidate). ## Out of scope - `structlog`. The indexing contract only needs `level` + `event`; the full `structlog` pipeline is more than we need for a single-container app. - Log shipping config — Promtail on the host handles it. ## Deliverables - Log config that produces JSON with `level` and `event` for both app and access logs. - Tests that verify the format (at minimum: parse one captured line as JSON, assert `level` and `event` keys). - Docs note: example LogQL queries for Quartermaster, mirroring the Archon contract's block. Tracks work that blocks first deploy per #25.