Merge pull request #1302 from joshunrau/debug-docs

format gateway logs as json, update express to v5 on gateway, add debug page to docs

Author: joshunrau

apps/gateway/package.json

@@ -25,10 +25,11 @@
     "@prisma/client": "catalog:",
     "axios": "catalog:",
     "compression": "^1.7.5",
-    "express": "^4.21.2",
+    "express": "^5.2.1",
     "lodash-es": "workspace:lodash-es__4.x@*",
-    "pino-http": "^10.4.0",
-    "pino-pretty": "^11.2.2",
+    "pino": "^10.3.1",
+    "pino-http": "^11.0.0",
+    "pino-pretty": "^13.1.3",
     "react": "workspace:react__19.x@*",
     "react-dom": "workspace:react-dom__19.x@*",
     "sirv": "^2.0.4",
@@ -41,7 +42,7 @@
     "@opendatacapture/vite-plugin-runtime": "workspace:*",
     "@tailwindcss/vite": "catalog:",
     "@types/compression": "^1.7.5",
-    "@types/express": "^4.17.21",
+    "@types/express": "^5.0.6",
     "@vitejs/plugin-react-swc": "^3.7.2",
     "esbuild": "catalog:",
     "nodemon": "catalog:",

apps/gateway/src/logger.ts

@@ -0,0 +1,10 @@
+import pino from 'pino';
+
+export const logger = pino(
+  {},
+  {
+    write: (message) => {
+      process.stdout.write(JSON.stringify(JSON.parse(message), null, 2) + '\n');
+    }
+  }
+);

apps/gateway/src/middleware/error-handler.middleware.ts

@@ -1,9 +1,10 @@
 import type { ErrorRequestHandler } from 'express';
 
+import { logger } from '@/logger';
 import { HttpException } from '@/utils/http-exception';
 
 export const errorHandlerMiddleware: ErrorRequestHandler = (err, _, res, next) => {
-  console.error(err);
+  logger.error(err);
   if (res.headersSent) {
     return next(err);
   } else if (err instanceof HttpException) {

apps/gateway/src/routers/api.router.ts

@@ -9,6 +9,7 @@ import type { GatewayHealthcheckSuccessResult } from '@opendatacapture/schemas/g
 import { Router } from 'express';
 
 import { prisma } from '@/lib/prisma';
+import { logger } from '@/logger';
 import { ah } from '@/utils/async-handler';
 import { HttpException } from '@/utils/http-exception';
 
@@ -42,7 +43,7 @@ router.post(
   ah(async (req, res) => {
     const result = await $CreateRemoteAssignmentData.safeParseAsync(req.body);
     if (!result.success) {
-      console.error(result.error.issues);
+      logger.error(result.error.issues);
       throw new HttpException(400, 'Bad Request');
     }
     const { instrumentContainer, publicKey, ...assignment } = result.data;
@@ -61,7 +62,7 @@ router.post(
 router.patch(
   '/assignments/:id',
   ah(async (req, res) => {
-    const id = req.params.id;
+    const id = req.params.id as string;
     const assignment = await prisma.remoteAssignmentModel.findFirst({
       where: { id }
     });
@@ -70,7 +71,7 @@ router.patch(
     }
     const result = await $UpdateRemoteAssignmentData.safeParseAsync(req.body);
     if (!result.success) {
-      console.error(result.error.issues);
+      logger.error(result.error.issues);
       throw new HttpException(400, 'Bad Request');
     }
     const { data, kind, status } = result.data;
@@ -114,7 +115,7 @@ router.patch(
 router.delete(
   '/assignments/:id',
   ah(async (req, res) => {
-    const id = req.params.id;
+    const id = req.params.id as string;
     const assignment = await prisma.remoteAssignmentModel.findFirst({
       where: { id }
     });

apps/gateway/src/routers/root.router.ts

@@ -2,6 +2,7 @@ import { $InstrumentBundleContainer } from '@opendatacapture/schemas/instrument'
 import { Router } from 'express';
 
 import { prisma } from '@/lib/prisma';
+import { logger } from '@/logger';
 import type { RootProps } from '@/Root';
 import { ah } from '@/utils/async-handler';
 import { generateToken } from '@/utils/auth';
@@ -11,7 +12,7 @@ const router = Router();
 router.get(
   '/assignments/:id',
   ah(async (req, res, next) => {
-    const id = req.params.id!;
+    const id = req.params.id! as string;
     const assignment = await prisma.remoteAssignmentModel.findFirst({
       where: { id }
     });
@@ -26,7 +27,7 @@ router.get(
 
     const targetParseResult = await $InstrumentBundleContainer.safeParseAsync(JSON.parse(assignment.targetStringified));
     if (!targetParseResult.success) {
-      console.error(targetParseResult.error.issues);
+      logger.error(targetParseResult.error.issues);
       return res.status(500).set({ 'Content-Type': 'application/json' }).json({
         error: 'Internal Server Error',
         message: 'Failed to parse target instrument from database',

apps/gateway/src/server/server.base.ts

@@ -1,11 +1,11 @@
 import express from 'express';
 import type { Request, Response } from 'express';
 import PinoHttp from 'pino-http';
-import PinoPretty from 'pino-pretty';
 import type { Promisable } from 'type-fest';
 
 import { config } from '@/config';
 import type { RenderFunction } from '@/entry-server';
+import { logger } from '@/logger';
 import { apiKeyMiddleware } from '@/middleware/api-key.middleware';
 import { errorHandlerMiddleware } from '@/middleware/error-handler.middleware';
 import type { RootProps } from '@/Root';
@@ -31,10 +31,8 @@ export abstract class BaseServer {
     } catch (err) {
       if (err instanceof Error) {
         this.fixStacktrace?.(err);
-        console.error(err.stack);
-      } else {
-        console.error(err);
       }
+      logger.error(err);
       res.status(500).json({ message: 'Internal Server Error', statusCode: 500 });
     }
   });
@@ -47,25 +45,21 @@ export abstract class BaseServer {
       })
     );
     this.app.use(
-      PinoHttp(
-        {
-          customLogLevel: (_, res) => {
-            return res.statusCode >= 500 ? 'error' : 'info';
-          },
-          serializers: {
-            req: (req: Request) => {
-              return `${req.method} ${req.url}`;
-            },
-            res: (res: Response) => {
-              return res.statusCode;
-            }
+      PinoHttp({
+        customLogLevel: (_, res) => {
+          return res.statusCode >= 500 ? 'error' : 'info';
+        },
+        logger,
+        serializers: {
+          req: (req: Request) => {
+            return `${req.method} ${req.url}`;
           },
-          wrapSerializers: false
+          res: (res: Response) => {
+            return res.statusCode;
+          }
         },
-        PinoPretty({
-          colorize: true
-        })
-      )
+        wrapSerializers: false
+      })
     );
     this.app.use('/api', apiKeyMiddleware, apiRouter);
     this.app.use('/', this.rootLoader, rootRouter);
@@ -76,8 +70,7 @@ export abstract class BaseServer {
 
   listen(port = config.port) {
     return this.app.listen(port, () => {
-      // eslint-disable-next-line no-console
-      console.log(`Server started at http://localhost:${port}`);
+      logger.info(`Server started at http://localhost:${port}`);
     });
   }
 

docs/en/2-tutorials/2.2-debugging.md

@@ -0,0 +1,33 @@
+---
+title: Debugging
+slug: en/docs/tutorials/debugging
+sidebar:
+  order: 2
+---
+
+When debugging, it’s important to distinguish between **client-side errors** (errors in the user’s browser) and **server-side errors** (errors from your backend services). Client-side issues appear in the browser console, while server-side issues are recorded by your running containers.
+
+### Client Logs
+
+To inspect client-side errors and warnings, open your browser’s developer tools and check the **Console** tab.
+
+### Server Logs
+
+Server logs are available through Docker. For example, you can view logs for a specific service with:
+
+```bash
+docker compose logs api
+```
+
+The API and Gateway logs are in JSON format, so you can filter and inspect them using jq. For example, to show only error-level logs from the last 24 hours:
+
+```bash
+docker compose logs api --no-log-prefix --since 24h | jq 'select(.level == "ERROR")'
+```
+
+### Reporting Issues
+
+If you encounter **500 Internal Server Errors** or unclear failures, please open an issue on our GitHub repository and include:
+
+- Relevant server logs (redacted if necessary)
+- Steps to reproduce the problem