Documento Skill originale
Contenuto dal repository con titoli, esempi, codice, tabelle, link e immagini preservati.
Logging and Observability
When to use
- Wiring observability for a new service
- Debugging cross-service requests
- Removing
console.logfrom production code
Core rules
- Structured JSON logs in production, pretty in development
- Every log entry has
timestamp,level,message,traceId - No
console.login production code - Correlation/trace ID passed through async context
- Health endpoint (
/health) and readiness endpoint (/ready)
Reference shape (TypeScript)
Logger Interface (Port)
typescript
export interface Logger {
info(message: string, meta?: Record<string, unknown>): void;
warn(message: string, meta?: Record<string, unknown>): void;
error(message: string, meta?: Record<string, unknown>): void;
debug(message: string, meta?: Record<string, unknown>): void;
}JSON Logger Implementation
typescript
export class JsonLogger implements Logger {
constructor(private traceId?: string) {}
info(message: string, meta?: Record<string, unknown>): void {
this.log('info', message, meta);
}
private log(level: string, message: string, meta?: Record<string, unknown>): void {
const entry = {
timestamp: new Date().toISOString(),
level,
message,
traceId: this.traceId,
...meta,
};
console.log(JSON.stringify(entry));
}
}Examples — Do
typescript
this.logger.info('User created', { userId: user.id, email: user.email.value });Examples — Don't
typescript
// ❌ Console.log in production code
console.log('User created:', user);
// ❌ No trace ID
logger.info('Request processed');Checklist
- [ ] Structured JSON logger implemented
- [ ] Trace/correlation ID in every log entry
- [ ] Health and readiness endpoints created
- [ ] No
console.login production code
See reference/logging-patterns.md for full patterns.
