Torben Sorensen
11aeac5edd
Some checks failed
Deploy to Test Environment / deploy-to-test (push) Failing after 1m10s
43 lines
1.3 KiB
Markdown
43 lines
1.3 KiB
Markdown
# 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
|
|
```
|