로그 레벨과 구조화 로깅 — 디버깅이 쉬워지는 로그 쓰기

핵심 요약

console.log를 아무렇게나 흩뿌리면, 정작 장애가 났을 때 수만 줄 속에서 원하는 걸 못 찾는다. 좋은 로그는 두 가지다 — ① 레벨(ERROR/WARN/INFO/DEBUG)로 중요도를 구분하고, ② 구조화(JSON)해서 기계가 검색·필터링할 수 있게 한다.

1. 로그 레벨

운영에서는 보통 INFO 이상만 남기고, 문제 조사 시 DEBUG를 켠다. 레벨이 있으면 "ERROR만 보기"가 가능해진다.

2. 구조화 로깅 — 텍스트 vs JSON

// ❌ 텍스트 — 검색·파싱 어려움
console.log('user 123 order 456 failed: timeout')

// ✅ 구조화 — 필드로 검색 가능
logger.error('order failed', {
  userId: 123, orderId: 456, reason: 'timeout',
  requestId: 'abc-…'
})
// → {"level":"error","msg":"order failed","userId":123,...}

JSON이면 로그 시스템에서 userId=123, level=error로 필터링·집계할 수 있다. 텍스트는 사람 눈으로만 읽힌다.

3. 꼭 넣을 필드

• 요청 ID(trace id) — 한 요청의 로그를 전부 이어보게 해준다(분산 환경 필수)
• 타임스탬프·레벨·서비스명
• 맥락(userId, 경로 등) — 단, 민감정보(비밀번호·토큰·주민번호)는 절대 남기지 마라

4. 함정

• 과도한 로깅 — 모든 걸 다 찍으면 비용↑·정작 중요한 게 묻힌다. 의미 있는 이벤트만.
• 민감정보 유출 — 로그에 카드번호·토큰이 찍히면 그 자체가 사고. 마스킹하라.
• 레벨 남용 — 다 ERROR로 찍으면 알림이 무의미해진다(늑대소년). 레벨을 정확히.

자주 묻는 질문

console.log만 써도 되지 않나요?

소규모 개발엔 괜찮지만, 운영에선 레벨 구분과 구조화가 없어 장애 시 원하는 로그를 찾기 어렵습니다. 로깅 라이브러리를 쓰면 레벨·JSON 출력·요청 ID 연동을 손쉽게 얻어, 나중에 훨씬 편해집니다.

요청 ID는 어떻게 넣나요?

요청이 들어올 때 고유 ID를 하나 만들어(또는 들어온 trace 헤더를 이어받아) 그 요청의 모든 로그에 같이 남깁니다. 미들웨어에서 컨텍스트에 저장해두고 로거가 자동으로 붙이게 하면, 한 요청의 흐름을 ID로 한 번에 추적할 수 있습니다.

로그를 얼마나 남겨야 하나요?

"이 로그가 장애 조사에 실제로 도움이 되는가"가 기준입니다. 정상 흐름의 핵심 이벤트와 모든 에러는 남기되, 반복되는 사소한 정보는 줄이세요. 과한 로그는 비용과 노이즈를 늘리고 정작 중요한 로그를 묻습니다.