Skip to content

Docs: document the log format and correct the level descriptions - #27

Merged
SandObserver merged 1 commit into
mainfrom
docs/logging
Aug 10, 2026
Merged

SandObserver merged 1 commit into
mainfrom
docs/logging

Conversation

@SandObserver

Copy link
Copy Markdown
Owner

Summary

  • Correct the claim in docs/support.md that both Nginx and the API log to stdout. Nginx sends request errors to stderr and keeps no access log.
  • Add a "What a log line looks like" section: the record shape, the five level abbreviations, that AUD is never filtered by the level setting, that the banner is unstructured and always prints, and that secrets are never logged.
  • Note that the format is logfmt, so | logfmt parses it in Loki or Grafana with no custom rules.
  • Link the LOG_LEVEL row in docs/architecture.md rather than restating the boot-versus-settings precedence it already covers.
  • State in both docs/architecture.md and docker-compose.yml that warn and error behave the same; they share a threshold, and listing four names implied four behaviours.
  • Add the Unreleased entries for this work, under Added, Changed, Fixed and Security.

Merged last of the five, so it describes what actually shipped. The level names the environment-table row check depends on are unchanged.

Testing
All green, including the Docker build. Documentation only; no new tests, and the existing environment-doc row checks still pass.

Checklist

  • Stays within the project constraints: one container, no runtime dependencies, no build step (see CONTRIBUTING.md).
  • Tests added or updated for new logic, and the full suite, lint, and typechecks pass.
  • Docs updated if behavior or configuration changed.
  • CHANGELOG.md updated under Unreleased if the change is user-visible.

The support doc said both Nginx and the API log to stdout. Nginx now sends
request errors to stderr and keeps no access log, so the claim is restated.

Adds the record shape, the five level abbreviations, the fact that audit
records are never filtered, and one line for anyone shipping to Loki, since
the format is logfmt and needs no custom parser.

warn and error share a threshold and behave identically. The Compose comment
and the environment table both listed four levels as though they were four
behaviours.
@SandObserver SandObserver added the documentation Improvements or additions to documentation label Aug 10, 2026
@SandObserver
SandObserver merged commit 8814822 into main Aug 10, 2026
3 checks passed
@SandObserver
SandObserver deleted the docs/logging branch August 10, 2026 21:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant