feat: add structured pino logging

README.md

@@ -89,6 +89,10 @@ API key for the metering flow until API-key enforcement lands. Add your own
 `X-Request-Id` header when you want to correlate client logs with backend
 responses. The backend echoes the value on success and structured errors.
 
+Structured logs default to `info` outside tests and `silent` in
+`NODE_ENV=test`. Set `LOG_LEVEL` to one of `fatal`, `error`, `warn`, `info`,
+`debug`, `trace`, or `silent` to override the default.
+
 Set a shell variable for the local base URL:
 
 ```bash

package.json

@@ -36,6 +36,7 @@
     "typescript-eslint": "^8.61.1"
   },
   "dependencies": {
-    "express": "^5.2.1"
+    "express": "^5.2.1",
+    "pino": "^10.3.1"
   }
 }

src/index.ts

@@ -1,4 +1,11 @@
 import express from "express";
+import {
+  logger,
+  logForcedShutdown,
+  logServerCloseError,
+  logServerStarted,
+  logShutdownSignal,
+} from "./logger.js";
 import {
   installPreRouteMiddleware,
   installRequestStateMiddleware,
@@ -46,20 +53,20 @@ const app = createApp();
 
 if (process.argv[1]?.endsWith("index.js") || process.argv[1]?.endsWith("index.ts")) {
   const server = app.listen(PORT, () => {
-    console.log(`AgentPay backend listening on port ${PORT}`);
+    logServerStarted(logger, PORT);
   });
 
   const shutdown = (signal: string) => {
-    console.log(`Received ${signal}, draining…`);
+    logShutdownSignal(logger, signal);
     server.close((err) => {
       if (err) {
-        console.error("server.close error:", err);
+        logServerCloseError(logger, err);
         process.exit(1);
       }
       process.exit(0);
     });
     setTimeout(() => {
-      console.error("Forced exit after 10s drain timeout");
+      logForcedShutdown(logger, 10_000);
       process.exit(1);
     }, 10_000).unref();
   };