0ff65b0b02
Update all user-facing strings (HTML title, manifest, header logo, browser title updater), code comments, and documentation references. Folder name retained as-is.
65 lines
2.3 KiB
Markdown
65 lines
2.3 KiB
Markdown
# Structured Logging
|
|
|
|
Codewalkers uses [pino](https://getpino.io/) for structured JSON logging on the backend.
|
|
|
|
## Architecture
|
|
|
|
- **pino** writes structured JSON to **stderr** so CLI user output on stdout stays clean
|
|
- **console.log** remains for CLI command handlers (user-facing output on stdout)
|
|
- The `apps/server/logging/` module (ProcessLogWriter/LogManager) is a separate concern — it captures per-agent process stdout/stderr to files
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|---------|
|
|
| `CW_LOG_LEVEL` | Log level override (`fatal`, `error`, `warn`, `info`, `debug`, `trace`, `silent`) | `info` (production), `debug` (development) |
|
|
| `CW_LOG_PRETTY` | Set to `1` for human-readable colorized output via pino-pretty | unset (JSON output) |
|
|
|
|
## Log Levels
|
|
|
|
| Level | Usage |
|
|
|-------|-------|
|
|
| `fatal` | Process will exit (uncaught exceptions, DB migration failure) |
|
|
| `error` | Operation failed (agent crash, parse failure, clone failure) |
|
|
| `warn` | Degraded (account exhausted, no accounts available, stale PID, reconcile marking crashed) |
|
|
| `info` | State transitions (agent spawned/stopped/resumed, dispatch decision, server started, account selected/switched) |
|
|
| `debug` | Implementation details (command being built, session ID extraction, worktree paths, schema selection) |
|
|
|
|
## Adding Logging to a New Module
|
|
|
|
```typescript
|
|
import { createModuleLogger } from '../logger/index.js';
|
|
|
|
const log = createModuleLogger('my-module');
|
|
|
|
// Use structured data as first arg, message as second
|
|
log.info({ taskId, agentId }, 'task dispatched');
|
|
log.error({ err: error }, 'operation failed');
|
|
log.debug({ path, count }, 'processing items');
|
|
```
|
|
|
|
## Module Names
|
|
|
|
| Module | Used in |
|
|
|--------|---------|
|
|
| `agent-manager` | `apps/server/agent/manager.ts` |
|
|
| `dispatch` | `apps/server/dispatch/manager.ts` |
|
|
| `http` | `apps/server/server/index.ts` |
|
|
| `server` | `apps/server/cli/index.ts` (startup) |
|
|
| `git` | `apps/server/git/manager.ts`, `apps/server/git/clone.ts`, `apps/server/git/project-clones.ts` |
|
|
| `db` | `apps/server/db/ensure-schema.ts` |
|
|
|
|
## Testing
|
|
|
|
Logs are silenced in tests via `CW_LOG_LEVEL=silent` in `vitest.config.ts`.
|
|
|
|
## Quick Start
|
|
|
|
```sh
|
|
# Pretty logs during development
|
|
CW_LOG_LEVEL=debug CW_LOG_PRETTY=1 cw --server
|
|
|
|
# JSON logs for production/piping
|
|
cw --server 2>server.log
|
|
```
|