§9 structured logging + OTLP observability (todo §9); structured, OTLP-native logging on @larvit/log (2.3.0, pinned; itself zero-dependency — the one new runtime dep). New pure src/logger.ts: createLogger() builds one app Log tagged service.name=plainpages (level/format/OTLP from config, injectable stdout/stderr); requestLogger() clones it per request (own root trace, inheriting level/format/streams/OTLP) into a "request" span, adopting an inbound W3C traceparent so a request continues an upstream proxy's distributed trace (malformed ⇒ fresh trace; clone honours a passed traceparent while dropping the parent's, unlike parentLog). app.ts builds the per-request log at the top of the handler and on res "close" (fires on completion AND abort, unlike "finish") emits one access line (method/path-without-query/status/ms/requestId, guarded) then end()s to flush the span (fire-and-forget .catch — a flaky collector never crashes a served request); the catch-all 500 + Ory-unreachable re-mint now log via reqLog.error/warn; static.ts mid-stream error takes an injected onError. server.ts builds the app logger, logs discovery/listen/shutdown, end()-flushes on SIGTERM/SIGINT (re-entry-guarded). bootstrap.ts events go structured (the human first-run banner stays raw). Config (environment-agnostic, fail-loud): LOG_LEVEL (info), LOG_FORMAT (text; prod compose → json), OTLP_ENDPOINT (unset ⇒ console-only; set ⇒ export logs + spans to an OTel Collector), OTLP_PROTOCOL (http/json|http/protobuf). compose: base sets LOG_FORMAT=json, dev override flips it to text. Tests-first: logger.test.ts (service.name/severity/level-gate/format, OTLP-only-when-endpoint, a stubbed-fetch proof it POSTs /v1/logs, requestLogger context-merge/own-root-trace/traceparent-continue/malformed-ignored), config.test.ts (4 toggles + validation), app.test.ts (live request emits the JSON access line), compose.test.ts (prod json / dev text). Stability-reviewer: APPROVE, no Critical/High (addressed both yellow nits — guarded access line + "finish"→"close" so aborted requests log; shutdown re-entry guard — and the green ones). README (config table, new Observability section, Status, Layout, runtime-deps) + AGENTS (deps) updated. typecheck + 326 units green (317 → 326).

src/server.ts

@@ -9,9 +9,13 @@ import { createJwksProvider } from "./jwks.ts";
 import { createKetoClient } from "./keto-client.ts";
 import { createKratosAdmin } from "./kratos-admin.ts";
 import { createKratosPublic } from "./kratos-public.ts";
+import { createLogger } from "./logger.ts";
 import { loadMenuConfig } from "./menu-config.ts";
 
 const config = loadConfig(); // validates the env (incl. enforced secrets) — fails loud at boot
+// App-level logger (§9): structured, OTLP-capable when OTLP_ENDPOINT is set. The hot path clones it
+// per request for access logging + a trace span (src/app.ts); console-only otherwise.
+const log = createLogger({ format: config.logFormat, level: config.logLevel, otlpEndpoint: config.otlpEndpoint, otlpProtocol: config.otlpProtocol });
 const menu = await loadMenuConfig(); // config/menu.ts override + branding — fails loud if malformed
 // Every outbound Ory call is bounded so a hung/silent Ory can't park a request handler forever.
 const oryFetch = withTimeout(fetch, config.oryTimeoutSec * 1000);
@@ -29,7 +33,7 @@ const jwks = await createJwksProvider(config.jwksUrl, { fetchImpl: oryFetch });
 const denylist = config.revocationDenylist ? createDenylist({ ttlSec: config.revocationTtlSec }) : undefined;
 
 const plugins = await discoverPlugins(); // scans plugins/, validates — fails loud on a bad plugin
-console.log(`Discovered ${plugins.length} plugin(s)${plugins.length ? `: ${plugins.map((p) => p.id).join(", ")}` : ""}`);
+log.info("plugins discovered", { count: plugins.length, ids: plugins.map((p) => p.id).join(", ") });
 await runBootHooks(plugins); // plugin onBoot — after discovery, before listen; a throw aborts boot
 
 const server = createApp({
@@ -42,14 +46,23 @@ const server = createApp({
   keto,
   kratos,
   kratosAdmin,
+  log,
   menu,
   plugins,
   secureCookies: config.secureCookies,
 }).listen(config.port, () => {
-  console.log(`Listening on http://localhost:${config.port}`);
+  log.info("listening", { port: config.port, url: `http://localhost:${config.port}` });
 });
 
-// Drain in-flight requests on container stop instead of cutting them mid-response.
+// Drain in-flight requests on container stop instead of cutting them mid-response, then flush any
+// pending OTLP export before exiting so the last logs/spans aren't lost. Guard re-entry so a second
+// signal (or SIGTERM-then-SIGINT during a slow drain) doesn't double-close or end() an ended log.
+let shuttingDown = false;
 for (const signal of ["SIGINT", "SIGTERM"] as const) {
-  process.on(signal, () => server.close(() => process.exit(0)));
+  process.on(signal, () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    log.info("shutting down", { signal });
+    server.close(() => void log.end().finally(() => process.exit(0)));
+  });
 }