fix: use Sentry breadcrumbs for proper structured logging field extraction

batalabs · batalabs · commit f26f3e6249b1 · 2025-10-18T16:47:46.000-04:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,9 +1,8 @@
 ## [1.11.2](https://github.com/typelets/typelets-api/compare/v1.11.1...v1.11.2) (2025-10-18)
 
-
 ### Bug Fixes
 
-* standardize logging with structured data and add cache monitoring support ([534bbe9](https://github.com/typelets/typelets-api/commit/534bbe9f476d3fb92fa40897cbcc68838df66dc7))
+- standardize logging with structured data and add cache monitoring support ([534bbe9](https://github.com/typelets/typelets-api/commit/534bbe9f476d3fb92fa40897cbcc68838df66dc7))
 
 ## [1.11.1](https://github.com/typelets/typelets-api/compare/v1.11.0...v1.11.1) (2025-10-18)
 
diff --git a/src/instrument.ts b/src/instrument.ts
@@ -11,10 +11,11 @@ if (process.env.SENTRY_DSN) {
 
     integrations: [
       nodeProfilingIntegration(),
-      // Send console.log, console.warn, and console.error calls as logs to Sentry
-      Sentry.consoleLoggingIntegration({ levels: ["log", "warn", "error"] }),
       // Automatic PostgreSQL query monitoring and performance tracking
       Sentry.postgresIntegration(),
+      // Only capture unexpected console.error (logger uses breadcrumbs for structured logging)
+      // This catches errors from third-party libraries or unexpected crashes
+      Sentry.captureConsoleIntegration({ levels: ["error"] }),
     ],
 
     // Send structured logs to Sentry
diff --git a/src/lib/logger.ts b/src/lib/logger.ts
@@ -1,3 +1,5 @@
+import * as Sentry from "@sentry/node";
+
 interface LogLevel {
   level: string;
   priority: number;
@@ -33,48 +35,69 @@ class Logger {
     return level.priority <= this.currentLogLevel.priority;
   }
 
-  private formatLog(
-    level: string,
+  private sendToSentry(
+    level: "error" | "warning" | "info" | "debug",
     message: string,
     meta: LogMetadata = {}
-  ): Record<string, unknown> {
-    return {
-      timestamp: new Date().toISOString(),
+  ): void {
+    // Send as breadcrumb for proper field extraction in Sentry
+    Sentry.addBreadcrumb({
       level,
-      service: this.service,
-      environment: this.environment,
-      version: this.version,
       message,
-      ...meta,
-    };
+      category: (meta.type as string) || "app",
+      data: {
+        service: this.service,
+        environment: this.environment,
+        version: this.version,
+        ...meta,
+      },
+    });
   }
 
   error(message: string, meta: LogMetadata = {}, error?: Error): void {
     if (this.shouldLog(LOG_LEVELS.error)) {
-      const logData = this.formatLog("error", message, meta);
+      const enrichedMeta = { ...meta };
       if (error) {
-        logData.errorMessage = error.message;
-        logData.errorStack = error.stack;
+        enrichedMeta.errorMessage = error.message;
+        enrichedMeta.errorStack = error.stack || "";
+      }
+
+      this.sendToSentry("error", message, enrichedMeta);
+
+      // Also send to console for CloudWatch
+      if (this.environment === "development") {
+        console.error(message, enrichedMeta);
       }
-      console.error(message, logData);
     }
   }
 
   warn(message: string, meta: LogMetadata = {}): void {
     if (this.shouldLog(LOG_LEVELS.warn)) {
-      console.warn(message, this.formatLog("warn", message, meta));
+      this.sendToSentry("warning", message, meta);
+
+      if (this.environment === "development") {
+        console.warn(message, meta);
+      }
     }
   }
 
   info(message: string, meta: LogMetadata = {}): void {
     if (this.shouldLog(LOG_LEVELS.info)) {
-      console.log(message, this.formatLog("info", message, meta));
+      this.sendToSentry("info", message, meta);
+
+      if (this.environment === "development") {
+        console.log(message, meta);
+      }
     }
   }
 
   debug(message: string, meta: LogMetadata = {}): void {
     if (this.shouldLog(LOG_LEVELS.debug)) {
-      console.log(message, this.formatLog("debug", message, meta));
+      this.sendToSentry("debug", message, meta);
+
+      if (this.environment === "development") {
+        console.log(message, meta);
+      }
     }
   }
 
diff --git a/src/version.ts b/src/version.ts
@@ -1,2 +1,2 @@
 // This file is automatically updated by semantic-release
-export const VERSION = "1.11.2"
+export const VERSION = "1.11.2";
diff --git a/src/websocket/auth/handler.ts b/src/websocket/auth/handler.ts
@@ -2,6 +2,7 @@ import { verifyToken } from "@clerk/backend";
 import { createHash, createHmac } from "crypto";
 import { AuthenticatedWebSocket, WebSocketMessage, WebSocketConfig } from "../types";
 import { ConnectionManager } from "../middleware/connection-manager";
+import { logger } from "../../lib/logger";
 
 interface AuthenticatedMessage {
   payload: WebSocketMessage;
@@ -41,7 +42,10 @@ export class AuthHandler {
 
     // Emergency cleanup if too many nonces (DoS protection)
     if (this.usedNonces.size > this.MAX_NONCES) {
-      console.warn(`Nonce storage exceeded limit (${this.MAX_NONCES}), clearing all nonces`);
+      logger.warn("Nonce storage exceeded limit, clearing all nonces", {
+        type: "websocket_security",
+        maxNonces: this.MAX_NONCES,
+      });
       this.usedNonces.clear();
     }
   }
@@ -124,8 +128,11 @@ export class AuthHandler {
         console.log(`User ${ws.userId} authenticated via WebSocket`);
       }
     } catch (error: unknown) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      console.error("WebSocket authentication failed", { error: errorMessage });
+      logger.error(
+        "WebSocket authentication failed",
+        { type: "websocket_auth_error" },
+        error instanceof Error ? error : new Error(String(error))
+      );
 
       const isTokenExpired = (error as Record<string, unknown>)?.reason === "token-expired";
 
@@ -161,21 +168,29 @@ export class AuthHandler {
     const MAX_MESSAGE_AGE = 5 * 60 * 1000; // 5 minutes
     if (messageAge > MAX_MESSAGE_AGE || messageAge < -60000) {
       // -60 seconds tolerance for clock skew
-      console.warn("Message rejected: timestamp out of range");
+      logger.warn("Message rejected: timestamp out of range", {
+        type: "websocket_security",
+        messageAge,
+        maxAge: MAX_MESSAGE_AGE,
+      });
       return false;
     }
 
     // 2. Check for replay attack using nonce
     const nonceKey = `${nonce}:${timestamp}`;
     if (this.usedNonces.has(nonceKey)) {
-      console.warn("Message rejected: nonce already used (replay attack)");
+      logger.warn("Message rejected: nonce already used (replay attack)", {
+        type: "websocket_security",
+      });
       return false;
     }
 
     try {
       // 3. Validate required parameters
       if (!jwtToken || !userId) {
-        console.error("Missing JWT token or user ID for signature verification");
+        logger.warn("Missing JWT token or user ID for signature verification", {
+          type: "websocket_security",
+        });
         return false;
       }
 
@@ -207,9 +222,10 @@ export class AuthHandler {
       const isValid = isValidRegenerated || isValidStored;
 
       if (!isValid) {
-        console.warn("Message signature verification failed for user", userId);
-      } else {
-        console.debug("Message signature verified successfully for user", userId);
+        logger.warn("Message signature verification failed", {
+          type: "websocket_security",
+          userId: userId || "unknown",
+        });
       }
 
       if (isValid) {
@@ -219,8 +235,11 @@ export class AuthHandler {
 
       return isValid;
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      console.error("Error verifying message signature", { error: errorMessage });
+      logger.error(
+        "Error verifying message signature",
+        { type: "websocket_auth_error" },
+        error instanceof Error ? error : new Error(String(error))
+      );
       return false;
     }
   }
@@ -239,7 +258,9 @@ export class AuthHandler {
     if (this.isAuthenticatedMessage(rawMessage)) {
       // This is an authenticated message, verify signature
       if (!ws.sessionSecret) {
-        console.warn("Authenticated message received but no session secret available");
+        logger.warn("Authenticated message received but no session secret available", {
+          type: "websocket_security",
+        });
         return null;
       }
 
@@ -250,7 +271,10 @@ export class AuthHandler {
         ws.userId
       );
       if (!isValid) {
-        console.warn("Message signature verification failed for user", ws.userId);
+        logger.warn("Message signature verification failed", {
+          type: "websocket_security",
+          userId: ws.userId || "unknown",
+        });
         return null;
       }
 
diff --git a/src/websocket/handlers/base.ts b/src/websocket/handlers/base.ts
@@ -67,12 +67,15 @@ export class BaseResourceHandler {
           return;
         }
       } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        console.error(`Error authorizing ${config.resourceType} ${config.operation}`, {
-          resourceType: config.resourceType,
-          operation: config.operation,
-          error: errorMessage,
-        });
+        logger.error(
+          `Error authorizing ${config.resourceType} ${config.operation}`,
+          {
+            type: "websocket_error",
+            resourceType: config.resourceType,
+            operation: config.operation,
+          },
+          error instanceof Error ? error : new Error(String(error))
+        );
         ws.send(
           JSON.stringify({
             type: "error",
diff --git a/src/websocket/handlers/notes.ts b/src/websocket/handlers/notes.ts
@@ -54,8 +54,11 @@ export class NoteHandler extends BaseResourceHandler {
         })
       );
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      console.error("Error joining note", { noteId: message.noteId, error: errorMessage });
+      logger.error(
+        "Error joining note",
+        { type: "websocket_error", noteId: message.noteId || "unknown" },
+        error instanceof Error ? error : new Error(String(error))
+      );
       ws.send(
         JSON.stringify({
           type: "error",
@@ -137,17 +140,21 @@ export class NoteHandler extends BaseResourceHandler {
               typeof value === "string" &&
               value !== "[ENCRYPTED]"
             ) {
-              console.warn(
-                `Note update: rejected plaintext ${key} for note ${message.noteId} - must be [ENCRYPTED]`
-              );
+              logger.warn("Note update: rejected plaintext field - must be [ENCRYPTED]", {
+                type: "security",
+                field: key,
+                noteId: message.noteId || "unknown",
+              });
               return;
             }
 
             filteredChanges[key] = value;
           } else {
-            console.warn(
-              `Note update: filtered out disallowed field '${key}' for note ${message.noteId}`
-            );
+            logger.warn("Note update: filtered out disallowed field", {
+              type: "security",
+              field: key,
+              noteId: message.noteId || "unknown",
+            });
           }
         });
 
@@ -209,9 +216,11 @@ export class NoteHandler extends BaseResourceHandler {
             })
           );
         } else {
-          console.warn(
-            `Note update: no valid changes found for note ${message.noteId}, attempted fields: ${Object.keys(message.changes || {}).join(", ")}`
-          );
+          logger.warn("Note update: no valid changes found", {
+            type: "validation",
+            noteId: message.noteId || "unknown",
+            attemptedFields: Object.keys(message.changes || {}).join(", "),
+          });
           ws.send(
             JSON.stringify({
               type: "error",
@@ -221,8 +230,11 @@ export class NoteHandler extends BaseResourceHandler {
         }
       }
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      console.error("Error handling note update", { noteId: message.noteId, error: errorMessage });
+      logger.error(
+        "Error handling note update",
+        { type: "websocket_error", noteId: message.noteId || "unknown" },
+        error instanceof Error ? error : new Error(String(error))
+      );
       ws.send(
         JSON.stringify({
           type: "error",
diff --git a/src/websocket/index.ts b/src/websocket/index.ts
@@ -78,9 +78,11 @@ export class WebSocketManager {
                 message: "Message too large. Maximum size is 1MB.",
               })
             );
-            console.warn(
-              `WebSocket message too large: ${data.length} bytes from user ${ws.userId || "unauthenticated"}`
-            );
+            logger.warn("WebSocket message too large", {
+              type: "websocket_security",
+              messageSize: data.length,
+              userId: ws.userId || "unauthenticated",
+            });
             return;
           }
 
@@ -129,11 +131,14 @@ export class WebSocketManager {
             );
           }
         } catch (error) {
-          const errorMessage = error instanceof Error ? error.message : String(error);
-          console.error("Error handling WebSocket message", {
-            messageType: rawMessage?.type || "unknown",
-            error: errorMessage,
-          });
+          logger.error(
+            "Error handling WebSocket message",
+            {
+              type: "websocket_error",
+              messageType: rawMessage?.type || "unknown",
+            },
+            error instanceof Error ? error : new Error(String(error))
+          );
 
           // WebSocket metrics WebSocket message errors
           // Error tracking available via console logs
@@ -166,7 +171,7 @@ export class WebSocketManager {
       });
 
       ws.on("error", (error: Error): void => {
-        console.error("WebSocket error", { error: error.message });
+        logger.error("WebSocket error", { type: "websocket_connection_error" }, error);
 
         // Send WebSocket connection errors to New Relic
         // WebSocket metrics WebSocket connection errors

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,2 @@`
`1`	`1`	`// This file is automatically updated by semantic-release`
`2`		`-export const VERSION = "1.11.2"`
	`2`	`+export const VERSION = "1.11.2";`