logging-and-observability
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseLogging and Observability
日志与可观测性
When to use
适用场景
- Wiring observability for a new service
- Debugging cross-service requests
- Removing from production code
console.log
- 为新服务搭建可观测性体系
- 调试跨服务请求
- 从生产代码中移除
console.log
Core rules
核心规则
- Structured JSON logs in production, pretty in development
- Every log entry has ,
timestamp,level,messagetraceId - No in production code
console.log - Correlation/trace ID passed through async context
- Health endpoint () and readiness endpoint (
/health)/ready
- 生产环境使用结构化JSON日志,开发环境使用美化输出格式
- 每条日志条目都包含 、
timestamp、level、messagetraceId - 生产代码中禁止使用
console.log - 关联/追踪ID通过异步上下文传递
- 提供健康检查端点()和就绪检查端点(
/health)/ready
Reference shape (TypeScript)
参考结构(TypeScript)
Logger Interface (Port)
Logger 接口(端口)
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;
}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
JSON Logger 实现
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));
}
}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 });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');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 in production code
console.log
See reference/logging-patterns.md for full patterns.
- 已实现结构化JSON日志器
- 每条日志条目都包含追踪/关联ID
- 已创建健康检查与就绪检查端点
- 生产代码中无
console.log
完整模式请参见 reference/logging-patterns.md