From 41ee888d3b1afd3f05005ccff6adedc99b259837 Mon Sep 17 00:00:00 2001
From: Jeff Smith <jeff@unbiasedgeek.com>
Date: Sun, 19 Apr 2026 11:37:27 -0600
Subject: [PATCH] docs: README Logs section and --log-config flag (#27)

---
 README.md | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 9cdec68..06cb6d0 100644
--- a/README.md
+++ b/README.md
@@ -37,11 +37,32 @@ The SQLite file lives at `./quartermaster.db` by default. Override with the
 ## Run
 
 ```sh
-uv run uvicorn quartermaster.main:app --reload
+uv run uvicorn quartermaster.main:app \
+    --log-config src/quartermaster/logconfig.json \
+    --reload
 ```
 
 Open http://127.0.0.1:8000.
 
+## Logs
+
+Logs are JSON on stdout. Each line has `level` and `event` as queryable
+Loki labels (indexed by Promtail on the deploy host), plus arbitrary
+extra fields in the JSON body.
+
+Example LogQL queries in Grafana Explore (Loki data source):
+
+```
+{container="quartermaster"} | json
+{container="quartermaster", event="http_request", status=~"5.."}
+{container="quartermaster", event="month_closed"} | json | line_format "{{.path}} {{.message}}"
+```
+
+HTTP access logs appear as `event="http_request"` with `method`, `path`,
+`status`, and `client_ip` extras. Application events (`month_created`,
+`month_closed`, `template_entry_updated`, `posting_added`,
+`posting_deleted`) fire at the matching mutation sites.
+
 ## Tests
 
 ```sh