flyer-crawler.projectium.com/docs/adr/0052-granular-debug-logging-strategy.md

ADR-052: Granular Debug Logging Strategy

Date: 2026-01-11

Status: Proposed

Context

Global log levels (INFO vs DEBUG) are too coarse. Developers need to inspect detailed debug information for specific subsystems (e.g., ai-service, db-pool) without being flooded by logs from the entire application.

Decision

We will adopt a namespace-based debug filter pattern, similar to the debug npm package, but integrated into our Pino logger.

1. Logger Namespaces: Every service/module logger must be initialized with a module property (e.g., logger.child({ module: 'ai-service' })).
2. Environment Filter: We will support a DEBUG_MODULES environment variable that overrides the log level for matching modules.

Implementation

In src/services/logger.server.ts:

const debugModules = (process.env.DEBUG_MODULES || '').split(',').map((s) => s.trim());

export const createScopedLogger = (moduleName: string) => {
  // If DEBUG_MODULES contains "ai-service" or "*", force level to 'debug'
  const isDebugEnabled = debugModules.includes('*') || debugModules.includes(moduleName);

  return logger.child({
    module: moduleName,
    level: isDebugEnabled ? 'debug' : logger.level,
  });
};

Usage

To debug only AI and Database interactions:

DEBUG_MODULES=ai-service,db-repo npm run dev