chore(server): leveled logger, quiet per-event chatter in production

Add a minimal logger that filters by LOG_LEVEL (error|warn|info|debug,
default info) and route per-connection lifecycle, per-broadcast counts
and per-poll state diffs through logger.debug so they're silent in
prod. Critical startup/shutdown lines stay at info; errors are
unchanged. Document LOG_LEVEL in .env.example.

Author: NateIsern

.env.example

@@ -27,3 +27,8 @@ PORT=8080
 # unauthenticated rate limit. Generate a fine-grained read-only token; leave
 # blank to use anonymous requests (lower rate limit).
 GITHUB_TOKEN=
+
+# Logging
+# error | warn | info (default) | debug.
+# At info, per-connection / per-broadcast / per-poll chatter is suppressed.
+LOG_LEVEL=info

server/lib/blockchain-monitor.ts

@@ -12,6 +12,7 @@ import {
   NetworkStatsEvent
 } from './websocket-types'
 import { blockCache } from './cache'
+import { logger } from './logger'
 
 export class BlockchainMonitor {
   private wsManager: WebSocketManager
@@ -47,24 +48,24 @@ export class BlockchainMonitor {
       })
     })
 
-    console.log('[BlockchainMonitor] Initialized with config:', this.config)
+    logger.debug('[BlockchainMonitor] Initialized with config:', this.config)
   }
 
   /**
    * Start monitoring blockchain for all configured networks
    */
   async start(): Promise<void> {
     if (this.isRunning) {
-      console.log('[BlockchainMonitor] Already running')
+      logger.debug('[BlockchainMonitor] Already running')
       return
     }
 
     if (!this.config.enabled) {
-      console.log('[BlockchainMonitor] WebSocket disabled, not starting')
+      logger.debug('[BlockchainMonitor] WebSocket disabled, not starting')
       return
     }
 
-    console.log('[BlockchainMonitor] Starting monitor...')
+    logger.debug('[BlockchainMonitor] Starting monitor...')
     this.isRunning = true
 
     // Initialize states for all networks
@@ -86,7 +87,7 @@ export class BlockchainMonitor {
     await this.pollAllNetworks()
     await this.pollNetworkStats()
 
-    console.log('[BlockchainMonitor] Monitor started successfully')
+    logger.info('[BlockchainMonitor] Monitor started successfully')
   }
 
   /**
@@ -97,7 +98,7 @@ export class BlockchainMonitor {
       return
     }
 
-    console.log('[BlockchainMonitor] Stopping monitor...')
+    logger.debug('[BlockchainMonitor] Stopping monitor...')
     this.isRunning = false
 
     if (this.pollInterval) {
@@ -110,15 +111,15 @@ export class BlockchainMonitor {
       this.statsInterval = null
     }
 
-    console.log('[BlockchainMonitor] Monitor stopped')
+    logger.info('[BlockchainMonitor] Monitor stopped')
   }
 
   /**
    * Initialize network state
    */
   private async initializeNetworkState(network: NetworkType): Promise<void> {
     try {
-      console.log(`[BlockchainMonitor] Initializing ${network} state...`)
+      logger.debug(`[BlockchainMonitor] Initializing ${network} state...`)
 
       const blockCount = await blockCache.getBlockCount(network)
       const block = await blockCache.getBlock(blockCount, network, true)
@@ -133,7 +134,7 @@ export class BlockchainMonitor {
         state.lastUpdate = new Date()
       }
 
-      console.log(`[BlockchainMonitor] ${network} initialized: Block ${blockCount}`)
+      logger.debug(`[BlockchainMonitor] ${network} initialized: Block ${blockCount}`)
     } catch (error) {
       console.error(`[BlockchainMonitor] Error initializing ${network}:`, error)
     }
@@ -162,7 +163,7 @@ export class BlockchainMonitor {
       const newBlockCount = await blockCache.getBlockCount(network)
 
       if (newBlockCount > state.blockHeight) {
-        console.log(`[BlockchainMonitor] ${network}: New blocks detected (${state.blockHeight} -> ${newBlockCount})`)
+        logger.debug(`[BlockchainMonitor] ${network}: New blocks detected (${state.blockHeight} -> ${newBlockCount})`)
 
         // Fetch new blocks
         for (let height = state.blockHeight + 1; height <= newBlockCount; height++) {
@@ -207,7 +208,7 @@ export class BlockchainMonitor {
         state.blockHash = block.hash
       }
 
-      console.log(`[BlockchainMonitor] ${network}: Broadcasting new block ${height} (${block.hash})`)
+      logger.debug(`[BlockchainMonitor] ${network}: Broadcasting new block ${height} (${block.hash})`)
 
       // Broadcast new block event
       const newBlockEvent: NewBlockEvent = {
@@ -249,7 +250,7 @@ export class BlockchainMonitor {
         mempoolInfo &&
         (mempoolInfo.size !== state.mempoolSize || mempoolInfo.bytes !== state.mempoolBytes)
       ) {
-        console.log(`[BlockchainMonitor] ${network}: Mempool changed (${state.mempoolSize} -> ${mempoolInfo.size} tx)`)
+        logger.debug(`[BlockchainMonitor] ${network}: Mempool changed (${state.mempoolSize} -> ${mempoolInfo.size} tx)`)
 
         state.mempoolSize = mempoolInfo.size
         state.mempoolBytes = mempoolInfo.bytes
@@ -326,7 +327,7 @@ export class BlockchainMonitor {
         }
         this.wsManager.broadcast(statsEvent, network)
 
-        console.log(`[BlockchainMonitor] ${network}: Broadcasted network stats update`)
+        logger.debug(`[BlockchainMonitor] ${network}: Broadcasted network stats update`)
       }
     } catch (error) {
       console.error(`[BlockchainMonitor] Error polling network stats for ${network}:`, error)

server/lib/logger.ts

@@ -0,0 +1,35 @@
+// Minimal log-level filter so debug-level chatter (per-connection lifecycle,
+// per-broadcast counts, per-poll state diffs) is silent in production by
+// default but can be re-enabled via LOG_LEVEL=debug.
+//
+// Levels follow the standard ordering: error > warn > info > debug. Setting
+// LOG_LEVEL=info (the default) drops anything tagged 'debug'.
+
+type Level = 'error' | 'warn' | 'info' | 'debug'
+
+const LEVELS: Record<Level, number> = { error: 0, warn: 1, info: 2, debug: 3 }
+
+function resolveLevel(): Level {
+  const raw = (process.env.LOG_LEVEL ?? 'info').toLowerCase()
+  return raw in LEVELS ? (raw as Level) : 'info'
+}
+
+const active = LEVELS[resolveLevel()]
+
+function emit(level: Level, args: unknown[]): void {
+  if (LEVELS[level] > active) return
+  // Route through the matching console method so structured log collectors
+  // (DO/Render/Vercel) keep their colouring and severity routing.
+  const fn =
+    level === 'error' ? console.error :
+    level === 'warn' ? console.warn :
+    console.log
+  fn(...args)
+}
+
+export const logger = {
+  error: (...args: unknown[]) => emit('error', args),
+  warn: (...args: unknown[]) => emit('warn', args),
+  info: (...args: unknown[]) => emit('info', args),
+  debug: (...args: unknown[]) => emit('debug', args),
+}

server/lib/websocket-handler.ts

@@ -12,6 +12,7 @@ import {
   SubscribeEvent,
   UnsubscribeEvent
 } from './websocket-types'
+import { logger } from './logger'
 
 // Initialize WebSocket manager and blockchain monitor
 const wsManager = getWebSocketManager({
@@ -36,7 +37,7 @@ const blockchainMonitor = getBlockchainMonitor(wsManager, {
 // Start blockchain monitor once at module load (this module is evaluated a
 // single time via the lazy import in server/index.ts).
 blockchainMonitor.start().then(() => {
-  console.log('[WebSocketHandler] Blockchain monitor started')
+  logger.info('[WebSocketHandler] Blockchain monitor started')
 }).catch(error => {
   console.error('[WebSocketHandler] Failed to start blockchain monitor:', error)
 })
@@ -53,7 +54,7 @@ export function handleConnection(ws: WebSocket, request: unknown, ip?: string):
     // Register connection
     connectionId = wsManager.register(ws, currentNetwork, ip)
 
-    console.log(`[WebSocketHandler] New connection: ${connectionId} from ${ip || 'unknown'}`)
+    logger.debug(`[WebSocketHandler] New connection: ${connectionId} from ${ip || 'unknown'}`)
 
     // Send welcome message
     const welcomeEvent: WebSocketEvent = {
@@ -83,7 +84,7 @@ export function handleConnection(ws: WebSocket, request: unknown, ip?: string):
 
     // Handle connection close
     ws.on('close', (code: number, reason: Buffer) => {
-      console.log(`[WebSocketHandler] Connection closed: ${connectionId} (${code}: ${reason.toString()})`)
+      logger.debug(`[WebSocketHandler] Connection closed: ${connectionId} (${code}: ${reason.toString()})`)
       if (connectionId) {
         wsManager.unregister(connectionId)
       }
@@ -257,7 +258,7 @@ function startHeartbeat(ws: WebSocket, connectionId: string): void {
  * Shutdown handler
  */
 export function shutdown(): void {
-  console.log('[WebSocketHandler] Shutting down...')
+  logger.info('[WebSocketHandler] Shutting down...')
   shutdownBlockchainMonitor()
   shutdownWebSocketManager()
 }

server/lib/websocket-manager.ts

@@ -8,6 +8,7 @@ import {
   WebSocketManagerConfig,
   ServerMessage
 } from './websocket-types'
+import { logger } from './logger'
 
 export class WebSocketManager {
   private connections: Map<string, ConnectionInfo>
@@ -69,7 +70,7 @@ export class WebSocketManager {
       this.connectionsByIP.get(ip)?.add(connectionId)
     }
 
-    console.log(`[WebSocketManager] Registered connection ${connectionId} for ${network} (Total: ${this.connections.size})`)
+    logger.debug(`[WebSocketManager] Registered connection ${connectionId} for ${network} (Total: ${this.connections.size})`)
 
     return connectionId
   }
@@ -100,7 +101,7 @@ export class WebSocketManager {
     // Remove main connection
     this.connections.delete(connectionId)
 
-    console.log(`[WebSocketManager] Unregistered connection ${connectionId} (Remaining: ${this.connections.size})`)
+    logger.debug(`[WebSocketManager] Unregistered connection ${connectionId} (Remaining: ${this.connections.size})`)
 
     return true
   }
@@ -134,7 +135,7 @@ export class WebSocketManager {
     events.forEach(event => connection.subscribedEvents.add(event))
     this.updateActivity(connectionId)
 
-    console.log(`[WebSocketManager] Connection ${connectionId} subscribed to:`, events)
+    logger.debug(`[WebSocketManager] Connection ${connectionId} subscribed to:`, events)
 
     return true
   }
@@ -172,7 +173,7 @@ export class WebSocketManager {
 
     this.updateActivity(connectionId)
 
-    console.log(`[WebSocketManager] Connection ${connectionId} switched to ${newNetwork}`)
+    logger.debug(`[WebSocketManager] Connection ${connectionId} switched to ${newNetwork}`)
 
     return true
   }
@@ -200,7 +201,7 @@ export class WebSocketManager {
     })
 
     if (sentCount > 0) {
-      console.log(`[WebSocketManager] Broadcasted ${event.type} to ${sentCount} connections`)
+      logger.debug(`[WebSocketManager] Broadcasted ${event.type} to ${sentCount} connections`)
     }
 
     return sentCount
@@ -313,7 +314,7 @@ export class WebSocketManager {
     inactiveConnections.forEach(id => {
       const connection = this.connections.get(id)
       if (connection) {
-        console.log(`[WebSocketManager] Closing inactive connection ${id}`)
+        logger.debug(`[WebSocketManager] Closing inactive connection ${id}`)
         try {
           connection.socket.close()
         } catch (error) {
@@ -324,15 +325,15 @@ export class WebSocketManager {
     })
 
     if (inactiveConnections.length > 0) {
-      console.log(`[WebSocketManager] Cleaned up ${inactiveConnections.length} inactive connections`)
+      logger.debug(`[WebSocketManager] Cleaned up ${inactiveConnections.length} inactive connections`)
     }
   }
 
   /**
    * Shutdown manager and close all connections
    */
   shutdown(): void {
-    console.log(`[WebSocketManager] Shutting down (${this.connections.size} active connections)`)
+    logger.info(`[WebSocketManager] Shutting down (${this.connections.size} active connections)`)
 
     // Clear cleanup interval
     if (this.cleanupInterval) {
@@ -354,7 +355,7 @@ export class WebSocketManager {
     this.connectionsByIP.clear()
     this.connectionsByNetwork.clear()
 
-    console.log('[WebSocketManager] Shutdown complete')
+    logger.info('[WebSocketManager] Shutdown complete')
   }
 }