2nd/10_Wiki/Topics/Coding/Observability_Structured_Logging.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
observability-structured-logging	Structured Logging — JSON 첫 줄부터	Coding	draft	B	conceptual	2026-05-09	2026-05-09	observability logging json vibe-coding	language applicable_to TypeScript / pino / winston Backend		JSON logs log fields log levels redaction

Structured Logging

console.log("user " + id + " did " + action) 은 grep 으로 찾기 어렵다. JSON 형태 + 일관된 필드명 + 적절한 level + 민감정보 redact 4가지 = 운영 가능한 로그.

📖 핵심 개념

• 한 로그 = 한 JSON 객체 (한 줄).
• 핵심 필드: time, level, msg, requestId, userId, service, version.
• 동적 데이터는 메시지에 끼우지 말고 필드로.
• 민감정보 자동 redact (token, password, card).

💻 코드 패턴

pino (Node, fast)

import pino from 'pino';

export const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  redact: {
    paths: ['req.headers.authorization', 'req.headers.cookie', '*.password', '*.token', '*.creditCard'],
    censor: '[REDACTED]',
  },
  base: {
    service: 'user-service',
    version: process.env.GIT_SHA,
    env: process.env.NODE_ENV,
  },
  timestamp: pino.stdTimeFunctions.isoTime,
});

// 사용
logger.info({ userId, action: 'login', ms: 42 }, 'user logged in');
// → {"time":"2026-05-09T...","level":"info","userId":"1","action":"login","ms":42,"msg":"user logged in", ...}

Request-scoped child logger

import { AsyncLocalStorage } from 'node:async_hooks';

const als = new AsyncLocalStorage<{ requestId: string; userId?: string }>();

app.use((req, res, next) => {
  const requestId = req.header('x-request-id') ?? crypto.randomUUID();
  als.run({ requestId }, () => next());
});

export function log() {
  const ctx = als.getStore() ?? {};
  return logger.child(ctx);
}

// 어디서나
log().info({ orderId }, 'created order');
// → 자동으로 requestId 포함

Level 가이드

• fatal: 프로세스 종료급.
• error: 처리 가능하지만 비정상.
• warn: 문제 신호 (재시도 발생, fallback 사용).
• info: 정상 핵심 이벤트 (사용자 가입, 결제 완료).
• debug: 흐름 추적. 운영에서는 끔.
• trace: 매우 상세. 로컬만.

메시지 vs 필드

// ❌ 동적 값을 메시지에
logger.info(`User ${userId} purchased ${productId} for ${amount}`);

// ✅ 필드로
logger.info({ userId, productId, amount }, 'purchase completed');
// 검색: amount > 100 같은 쿼리 가능

🤔 의사결정 기준

데이터	어디
식별자 (userId, orderId)	항상 필드
타이밍 (ms, duration)	필드
에러 객체	{ err } (pino 자동 stack 추출)
요청 / 응답 본문	필드 + redact 정책
PII	절대 X — 별도 audit log

❌ 안티패턴

• stdout 에 plain text: 파싱 불가. JSON 한 줄.
• stderr 와 stdout 혼용: error 가 다른 stream 에. 한 곳으로 + level 필드.
• 민감정보 raw: token / password / 카드번호 / 주민번호. redact 정책 필수.
• 메시지 안에 stack trace: 한 줄 깨짐. 별도 err 필드.
• 로그 너무 verbose (debug 가 prod): 비용 / 노이즈. 필요시 dynamic level.
• 로그 너무 적음: 사고 시 디버깅 불가. critical path 는 info.
• timestamp 가 local timezone: 분산 시스템에서 헷갈림. ISO8601 UTC.
• 한 줄에 여러 JSON 객체: 파서 깨짐. 한 줄 = 한 JSON.

🤖 LLM 활용 힌트

• "console.log 금지. logger 사용. 동적 값은 필드, 메시지는 정적" 강제.
• AsyncLocalStorage 로 requestId 자동 주입.

🔗 관련 문서

• Observability_Correlation_IDs
• Observability_Error_Reporting