From 444044b99a830560a073b016707038a06ccd23c8 Mon Sep 17 00:00:00 2001
From: nholtware <noahryanholt@gmail.com>
Date: Thu, 5 Nov 2026 10:54:12 -0600
Subject: [PATCH] feat: JSON access log in the platform logging contract

---
 CLAUDE.md                        |  1 +
 Dockerfile                       |  3 +++
 README.md                        |  7 +++++++
 docker-entrypoint.d/10-config.sh | 10 +++++++++-
 nginx/default.conf               | 26 ++++++++++++++++++++++++++
 5 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index dc73156..5324714 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -5,5 +5,6 @@
 - Routes: table in `src/routes.tsx`, one component per file in `src/routes/`, loaders exported next to their component.
 - Runtime config: read only via `getConfig()` (`src/lib/config.ts`). A new browser-visible env var must be added to `VARS` in `docker-entrypoint.d/10-config.sh`, `AppConfig`, and the gitops Deployment. No secrets: config.js is public.
 - Backend calls: `apiGet()` in `src/lib/api.ts`, relative to `API_BASE_URL` (`/api` same-host ingress path, stripped before the backend). No CORS.
+- Logging: nginx access log is JSON in the platform logging contract (`log_format contract` in `nginx/default.conf`; `$app_name`/`$git_sha` from `conf.d/service-vars.conf` written by `10-config.sh`). Keep field names identical to the backend template's pino-http lines.
 - Serving contract: port 8080, `/healthz` 200, SPA fallback, immutable `/assets/`, no-cache `index.html`/`config.js` (`nginx/default.conf`).
 - Deploy: push to `main` -> Forgejo CI -> image -> gitops bump -> ArgoCD. Never `kubectl apply` by hand.
diff --git a/Dockerfile b/Dockerfile
index 9ca9be2..5aeda14 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -15,4 +15,7 @@ COPY nginx/default.conf /etc/nginx/conf.d/default.conf
 COPY --chmod=0755 docker-entrypoint.d/10-config.sh /docker-entrypoint.d/10-config.sh
 # html dir owned by nginx so 10-config.sh can write config.js at start.
 COPY --from=build --chown=101:101 /app/dist /usr/share/nginx/html
+# Logged as "version" in every access-log line.
+ARG GIT_SHA=dev
+ENV GIT_SHA=${GIT_SHA}
 EXPOSE 8080
diff --git a/README.md b/README.md
index a2d8c3a..2417e60 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,13 @@ Everything in `config.js` is public. Never put secrets there.
 - nginx listens on 8080: `/healthz` returns 200, unknown paths fall back to
   `index.html`, `/assets/*` are cached as immutable, and `index.html` and
   `config.js` are not cached.
+- Access log: one JSON line per request in the platform logging contract
+  (`level`, `time`, `service` = `APP_NAME`, `version` = `GIT_SHA`, `req.id`
+  (echoes `X-Request-Id`), `req.method`, `req.url`, `res.statusCode`,
+  `responseTime` in ms, `msg: "request completed"`), the same shape as the backend
+  template. In Kibana (http://kibana.192.168.1.83.nip.io, data view `kube-*`):
+  `service:"hello-web" and res.statusCode >= 400`. `/healthz` isn't logged.
+  nginx's own startup/error lines stay plain text (field `log`).
 
 ## Deploy
 
diff --git a/docker-entrypoint.d/10-config.sh b/docker-entrypoint.d/10-config.sh
index c4f4ee0..2aa90ae 100755
--- a/docker-entrypoint.d/10-config.sh
+++ b/docker-entrypoint.d/10-config.sh
@@ -23,4 +23,12 @@ for name in $VARS; do
 done
 
 printf 'window.__APP_CONFIG__ = {%s};\n' "$body" > "$OUT"
-echo "10-config.sh: wrote $OUT"
+
+# nginx variables for the JSON access log (nginx/default.conf). Restricted
+# charset: these land inside nginx string literals.
+safe() { printf '%s' "$1" | tr -cd 'A-Za-z0-9._-'; }
+cat > /etc/nginx/conf.d/service-vars.conf <<NGINX
+map \$host \$app_name { default "$(safe "$APP_NAME")"; }
+map \$host \$git_sha { default "$(safe "${GIT_SHA:-dev}")"; }
+NGINX
+echo "10-config.sh: wrote $OUT and service-vars.conf"
diff --git a/nginx/default.conf b/nginx/default.conf
index eb77927..4c4a107 100644
--- a/nginx/default.conf
+++ b/nginx/default.conf
@@ -1,7 +1,33 @@
+# Access log in the platform logging contract (same shape as the backend
+# template's pino-http lines), so Fluent Bit turns every key into a Kibana
+# field. $app_name / $git_sha come from conf.d/service-vars.conf, written at
+# container start by docker-entrypoint.d/10-config.sh.
+map $status $log_level {
+    ~^5     error;
+    default info;
+}
+# Echo X-Request-Id if the caller sent one, else nginx's own id.
+map $http_x_request_id $req_id {
+    ""      $request_id;
+    default $http_x_request_id;
+}
+# $request_time is seconds ("0.002"); the contract's responseTime is integer ms.
+map $request_time $response_ms {
+    "~^0\.0*(?<ms>\d+)$"             $ms;
+    "~^(?<s>[1-9]\d*)\.(?<ms>\d{3})$" $s$ms;
+    default                          0;
+}
+log_format contract escape=json
+    '{"level":"$log_level","time":"$time_iso8601","service":"$app_name",'
+    '"version":"$git_sha","req":{"id":"$req_id","method":"$request_method",'
+    '"url":"$request_uri"},"res":{"statusCode":$status},'
+    '"responseTime":$response_ms,"msg":"request completed"}';
+
 server {
     listen 8080;
     server_name _;
     root /usr/share/nginx/html;
+    access_log /dev/stdout contract;
 
     # Liveness/readiness for k8s probes.
     location = /healthz {