logging-and-observability

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Logging and Observability

日志与可观测性

When to use

适用场景

  • Wiring observability for a new service
  • Debugging cross-service requests
  • Removing
    console.log
    from production code
  • 为新服务搭建可观测性体系
  • 调试跨服务请求
  • 从生产代码中移除
    console.log

Core rules

核心规则

  1. Structured JSON logs in production, pretty in development
  2. Every log entry has
    timestamp
    ,
    level
    ,
    message
    ,
    traceId
  3. No
    console.log
    in production code
  4. Correlation/trace ID passed through async context
  5. Health endpoint (
    /health
    ) and readiness endpoint (
    /ready
    )
  1. 生产环境使用结构化JSON日志,开发环境使用美化输出格式
  2. 每条日志条目都包含
    timestamp
    、
    level
    、
    message
    、
    traceId
  3. 生产代码中禁止使用
    console.log
  4. 关联/追踪ID通过异步上下文传递
  5. 提供健康检查端点(
    /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
    console.log
    in production code
See reference/logging-patterns.md for full patterns.
  • 已实现结构化JSON日志器
  • 每条日志条目都包含追踪/关联ID
  • 已创建健康检查与就绪检查端点
  • 生产代码中无
    console.log
完整模式请参见 reference/logging-patterns.md