# 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`:

```typescript
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:

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