feat(app): add structured server-side logging (#745)

Author: danadajian

app/backend/src/acceptVisualChanges.ts

@@ -1,3 +1,4 @@
+import { logEvent } from './logger';
 import { S3Client } from './s3Client';
 import {
   BASE_IMAGE_NAME,
@@ -26,14 +27,21 @@ export const acceptVisualChanges = async ({
   if (reasonToPreventUpdate) {
     throw new TRPCError({
       code: 'FORBIDDEN',
-      message: reasonToPreventUpdate
+      message: reasonToPreventUpdate,
+      cause: {
+        event: 'VISUAL_CHANGE_ACCEPTANCE_BLOCKED',
+        owner,
+        repo,
+        commitHash
+      }
     });
   }
   const hash = commitHash ?? diffId;
   if (!hash) {
     throw new TRPCError({
       code: 'BAD_REQUEST',
-      message: 'Please provide either a commitHash or a diffId.'
+      message: 'Please provide either a commitHash or a diffId.',
+      cause: { event: 'MISSING_IDENTIFIER', owner, repo }
     });
   }
 
@@ -53,6 +61,13 @@ export const acceptVisualChanges = async ({
   if (commitHash) {
     await updateCommitStatus({ owner, repo, commitHash });
   }
+  logEvent('INFO', {
+    event: 'VISUAL_CHANGES_ACCEPTED',
+    owner,
+    repo,
+    hash,
+    baseImagesUpdated: useBaseImages
+  });
 };
 
 export const filterNewImages = (s3Paths: string[]) => {

app/backend/src/fetchCurrentPage.ts

@@ -14,7 +14,14 @@ export const fetchCurrentPage = async ({
   if (!currentPage?.keys) {
     throw new TRPCError({
       code: 'NOT_FOUND',
-      message: `Page ${page} does not exist. Only ${paginatedKeys.length} pages were found.`
+      message: `Page ${page} does not exist. Only ${paginatedKeys.length} pages were found.`,
+      cause: {
+        event: 'PAGE_NOT_FOUND',
+        hash,
+        bucket,
+        page,
+        totalPages: paginatedKeys.length
+      }
     });
   }
   const { keys, title } = currentPage;
@@ -24,7 +31,8 @@ export const fetchCurrentPage = async ({
       if (!result.success) {
         throw new TRPCError({
           code: 'BAD_REQUEST',
-          message: `Invalid file name: ${key}. ${result.error.message}`
+          message: `Invalid file name: ${key}. ${result.error.message}`,
+          cause: { event: 'INVALID_FILE_NAME', hash, bucket, key }
         });
       }
 

app/backend/src/getGroupedKeys.ts

@@ -10,7 +10,8 @@ export const getGroupedKeys = async (hash: string, bucket: string) => {
     throw new TRPCError({
       code: 'NOT_FOUND',
       message:
-        'The commit hash was not associated with any visual regression test failures.'
+        'The commit hash was not associated with any visual regression test failures.',
+      cause: { event: 'COMMIT_HASH_NOT_FOUND', hash, bucket }
     });
   }
 
@@ -34,7 +35,8 @@ export const getGroupedKeys = async (hash: string, bucket: string) => {
     throw new TRPCError({
       code: 'NOT_FOUND',
       message:
-        'There was no new or diff images associated with the commit hash.\nThis might be because the tests failed before a picture could be taken and it could be compared to the base.'
+        'There was no new or diff images associated with the commit hash.\nThis might be because the tests failed before a screenshot could be taken and it could be compared to the base.',
+      cause: { event: 'NO_NEW_OR_DIFF_IMAGES', hash, bucket }
     });
   }
 

app/backend/src/getOctokit.ts

@@ -8,23 +8,26 @@ export const getOctokit = (owner: string, repo: string) => {
   if (!existsSync(secretsFilePath)) {
     throw new TRPCError({
       code: 'UNAUTHORIZED',
-      message: 'Missing secrets.json file'
+      message: 'Missing secrets.json file',
+      cause: { event: 'MISSING_SECRETS_FILE', owner, repo, secretsFilePath }
     });
   }
   const parsedJson = JSON.parse(readFileSync(secretsFilePath).toString());
   const result = secretsJsonSchema.safeParse(parsedJson);
   if (!result.success) {
     throw new TRPCError({
       code: 'INTERNAL_SERVER_ERROR',
-      message: `Failed to parse secrets.json: ${result.error}`
+      message: `Failed to parse secrets.json: ${result.error}`,
+      cause: { event: 'SECRETS_PARSE_ERROR', owner, repo, error: result.error }
     });
   }
   const repoSecrets = result.data[`${owner}/${repo}`];
   const { githubToken, githubApiUrl } = repoSecrets ?? {};
   if (!githubToken) {
     throw new TRPCError({
       code: 'UNAUTHORIZED',
-      message: `Missing githubToken for repo ${owner}/${repo}`
+      message: `Missing githubToken for repo ${owner}/${repo}`,
+      cause: { event: 'MISSING_GITHUB_TOKEN', owner, repo }
     });
   }
   return new Octokit({

app/backend/src/logger.ts

@@ -0,0 +1,9 @@
+export const logEvent = (
+  level: 'INFO' | 'WARN' | 'ERROR',
+  payload: Record<string, unknown>
+) => {
+  // eslint-disable-next-line no-console
+  console.log(
+    JSON.stringify({ timestamp: new Date().toISOString(), level, ...payload })
+  );
+};

app/backend/src/updateCommitStatus.ts

@@ -21,7 +21,14 @@ export const updateCommitStatus = async ({
     .catch(error => {
       throw new TRPCError({
         code: 'INTERNAL_SERVER_ERROR',
-        message: `Failed to update GitHub commit status: ${error}`
+        message: `Failed to update GitHub commit status: ${error}`,
+        cause: {
+          event: 'COMMIT_STATUS_UPDATE_FAILED',
+          owner,
+          repo,
+          commitHash,
+          error
+        }
       });
     });
 };

app/backend/test/getGroupedKeys.test.ts

@@ -102,7 +102,7 @@ describe('getGroupedKeys', () => {
       ]
     }));
     expect(getGroupedKeys('hash', 'bucket')).rejects.toThrow(
-      'There was no new or diff images associated with the commit hash.\nThis might be because the tests failed before a picture could be taken and it could be compared to the base.'
+      'There was no new or diff images associated with the commit hash.\nThis might be because the tests failed before a screenshot could be taken and it could be compared to the base.'
     );
   });
 });

app/server.ts

@@ -1,4 +1,5 @@
 import { router } from './backend/src/router';
+import { logEvent } from './backend/src/logger';
 import { createBunHttpHandler } from 'trpc-bun-adapter';
 import { serve, file } from 'bun';
 import { join } from 'path';
@@ -7,14 +8,29 @@ import index from './public/index.html';
 const IS_PROD = process.env.NODE_ENV === 'production';
 const DIST_DIR = join(import.meta.dir, 'dist');
 
+const trpcHandler = createBunHttpHandler({
+  router,
+  endpoint: '/trpc',
+  onError: ({ error: { code, message, cause }, path }) => {
+    const event =
+      cause && 'event' in cause && typeof cause.event === 'string'
+        ? cause.event
+        : 'UNKNOWN';
+    const causeWithEvent = {
+      ...cause,
+      event
+    };
+    logEvent('ERROR', { path, code, message, cause: causeWithEvent });
+  }
+});
+
 const server = serve({
   routes: {
     '/': IS_PROD ? file(join(DIST_DIR, 'index.html')) : index,
     '/health': new Response('healthy', { status: 200 })
   },
   port: process.env.PORT ?? 8080,
   async fetch(request, response) {
-    const trpcHandler = createBunHttpHandler({ router, endpoint: '/trpc' });
     const trpcResponse = trpcHandler(request, response);
     if (trpcResponse) return trpcResponse;
 
@@ -29,4 +45,4 @@ const server = serve({
   }
 });
 
-console.log(`Server running at ${server.url}`);
+logEvent('INFO', { message: `Server running at ${server.url}` });

eslint.config.js

@@ -23,6 +23,13 @@ export default [
       '@typescript-eslint/no-namespace': 'off'
     }
   },
+  {
+    files: ['app/**/*.ts', 'app/**/*.tsx'],
+    ignores: ['app/build.ts'],
+    rules: {
+      'no-console': ['error']
+    }
+  },
   {
     ignores: [
       '**/.tsup',