MythEclipseandClaude Opus 4.7
97648604d7
Design for migrating from Pino to Winston with hybrid console/file logging, npm-standard log levels, and dependency cleanup. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
116 lines
3.3 KiB
Markdown
116 lines
3.3 KiB
Markdown
# Winston Logging Refactor Design
|
|
|
|
## Goal
|
|
|
|
Refactor project logging from Pino to Winston and clean up logging-related dependencies without changing application behavior.
|
|
|
|
## Scope
|
|
|
|
- Replace `pino` and `pino-pretty` with `winston`.
|
|
- Remove `pino-http` if no code still uses it.
|
|
- Keep logging access centralized in `src/logger.ts`.
|
|
- Preserve current exported logger API shape where practical: `logger` and `createChildLogger(context)`.
|
|
- Normalize log output and levels across the codebase.
|
|
- Avoid unrelated feature work or broad refactors.
|
|
|
|
## Logging Architecture
|
|
|
|
`src/logger.ts` remains the only logging entry point. It will create one Winston logger with npm levels:
|
|
|
|
- `error`
|
|
- `warn`
|
|
- `info`
|
|
- `http`
|
|
- `verbose`
|
|
- `debug`
|
|
- `silly`
|
|
|
|
`LOG_LEVEL` validation will be updated to accept these Winston standard levels. Default behavior stays environment-aware: development can log more detail, production stays concise.
|
|
|
|
## Outputs
|
|
|
|
Winston will write to:
|
|
|
|
1. Console
|
|
- Pretty, colorized, timestamped output.
|
|
- Includes logger context, message, and metadata.
|
|
2. `logs/app.log`
|
|
- JSON format.
|
|
- Includes all logs at configured level and above.
|
|
3. `logs/error.log`
|
|
- JSON format.
|
|
- Includes error-level logs only.
|
|
|
|
The logger should create the `logs/` directory at runtime if needed. `logs/` should be ignored by git.
|
|
|
|
## Metadata and Error Handling
|
|
|
|
Existing log calls mostly remain valid. `src/logger.ts` will format metadata centrally so individual call sites do not need custom serialization.
|
|
|
|
Handled metadata shapes:
|
|
|
|
- `{ error: err }`
|
|
- `{ err }`
|
|
- `{ reason }`
|
|
- extra plain objects used by existing log calls
|
|
|
|
Errors should serialize with message, stack, name, code, statusCode, and any relevant enumerable fields. Non-error metadata should pass through without lossy conversion.
|
|
|
|
## Code Changes
|
|
|
|
Expected files:
|
|
|
|
- `package.json` and lockfile: add `winston`, remove Pino packages that become unused.
|
|
- `src/logger.ts`: rewrite from Pino to Winston.
|
|
- `src/config.ts`: expand `LOG_LEVEL` schema.
|
|
- `.gitignore`: ignore `logs/` if missing.
|
|
- Logger call sites: update only if TypeScript or Winston format compatibility requires it.
|
|
|
|
Known logger consumers include:
|
|
|
|
- `src/index.ts`
|
|
- `src/webserver.ts`
|
|
- `src/middleware.ts`
|
|
- `src/voiceController.ts`
|
|
- `src/media/mediaController.ts`
|
|
- `src/media/screenShareController.ts`
|
|
- `src/moderation/broadcaster.ts`
|
|
- `src/moderation/messageCapture.ts`
|
|
- `src/streaming/transcoder.ts`
|
|
|
|
Additional consumers should be found by grep during implementation.
|
|
|
|
## Dependency Cleanup
|
|
|
|
Remove packages only after confirming no imports remain:
|
|
|
|
- `pino`
|
|
- `pino-pretty`
|
|
- `pino-http`
|
|
|
|
Do not remove unrelated dependencies in this pass.
|
|
|
|
## Testing and Verification
|
|
|
|
Run:
|
|
|
|
- `pnpm install` or equivalent lockfile update after dependency changes.
|
|
- `pnpm run typecheck`
|
|
- `pnpm run test`
|
|
- `pnpm run lint`
|
|
|
|
Also verify log behavior with a short runtime command or startup check:
|
|
|
|
- console output is readable and includes context.
|
|
- `logs/app.log` is created.
|
|
- `logs/error.log` is created when an error log occurs.
|
|
|
|
## Success Criteria
|
|
|
|
- No Pino imports remain.
|
|
- Winston is the only logging backend.
|
|
- Existing application logging calls compile.
|
|
- Log levels are consistent and configurable via `LOG_LEVEL`.
|
|
- Console and file logging both work.
|
|
- Tests, typecheck, and lint pass.
|