프로덕션 API·워커 로그를 JSON 한 줄 구조화로 맞추는 체크리스트. 필드 표준(service·version·request_id), 레벨 정책, 개인정보·시크릿 redaction, 상관 ID 전파, 샘플링·보관 비용, 알림·대시보드 게이트, Node.js pino·Python 최소 설정까지 약 45항목. 백엔드·데브옵스·보안·개발자가 배포 전 15분 점검과 월간 볼륨 리뷰에 쓰는 실무 가이드. 국내 카드 결제 웹훅·BFF 로그 운영에도 동일 적용.
프로덕션에서 로그가 평문 한 줄·console.log 나열이면, 장애 시 “언제·어느 요청·어느 사용자 구간인지”를 10분 안에 못 찾는 경우가 많습니다. 구조화 로그(JSON 한 줄 + 고정 필드 + 레벨 정책)로 바꾸면 검색·알림·보관 비용이 같은 도구 안에서도 크게 달라집니다.
체크 순서는 필드 표준 → 레벨 → 개인정보 마스킹 → 상관 ID → 용량·보관 → 알림 게이트 → 배포 직전 점검이고, 약 45개 항목입니다. Node.js·Python API, 워커, 엣지 BFF 공통입니다. 트레이스 전용 파이프라인은 오픈텔레메트리 가이드와 병행하고, 아래는 “로그 한 줄에 무엇을 넣을지”에 맞춥니다.
로컬에서 사람이 읽는 로그와, 프로덕션에서 시스템이 집계하는 로그는 목적이 다릅니다. 요청이 초당 수십 건만 넘어도 문자열 검색만으로는 SLO 위반 원인을 못 좁힙니다. 아래 표는 “지금 당장 JSON 구조화로 갈지”를 고르는 기준입니다.
| 상황 | 평문 console 유지 | 구조화 JSON 권장 |
|---|---|---|
| 개발 머신 단독 디버그 | 가능 (짧은 수명) | 선택 |
| 스테이징·프리뷰 공유 | 비권장 | 필수에 가깝다 |
| 프로덕션 API·워커 | 금지에 가깝다 | 필수 |
| 알림·대시보드 연동 | 정규식 지옥 | 필드 필터로 끝 |
| 감사·컴플라이언스 요구 | 부적합 | 보관·마스킹 정책과 세트 |
12-Factor 앱 가이드도 로그를 “이벤트 스트림”으로 취급하고, 앱은 파일에 쓰지 말고 stdout으로 내보내라고 합니다. 수집·파싱·보관은 플랫폼(에이전트·사이드카·호스팅 로그 드레인) 몫입니다. 관련 배포 게이트는 프로덕션 배포 체크리스트와 맞춰 두면 누락이 줄어듭니다.
한 줄 원칙 — 프로덕션 로그 한 줄 = JSON 객체 하나. 여러 줄 스택은 stack 필드 문자열로 넣고, 사람이 읽기 쉬운 메시지 필드는 유지하되 검색 키는 별도 필드로 둡니다.
필드 이름이 서비스마다 다르면 중앙 로그에서 “에러율” 하나를 뽑는 데도 팀이 각자 쿼리를 짭니다. 최소 공통 스키마를 문서 한 장에 고정하세요. 라이브러리 예시는 pino(Node)·structlog/loguru 설정(Python)·slog(Go) 모두 동일 키를 맞추면 됩니다.
HTTP 라우트는 실제 경로(/users/123) 대신 템플릿 경로(/users/:id)를 쓰는 편이 카디널리티가 낮습니다. 사용자 ID는 필요하면 해시·내부 ID로 두고, 이메일·전화는 기본 필드에 넣지 않습니다.
레벨이 느슨하면 두 가지가 동시에 납니다. 하나는 디스크·인덱싱 비용 폭주, 다른 하나는 진짜 장애 신호가 노이즈에 묻히는 일입니다. 팀 합의 없이 “일단 info”를 남발하지 마세요.
| 레벨 | 쓰는 때 | 알림 기본 |
|---|---|---|
| debug | 개발 추적, 분기 값, 캐시 히트 상세 | 알림 없음 |
| info | 비즈니스 이벤트, 배포 기동, 중요 상태 전환 | 대시보드·감사 |
| warn | 재시도 성공, 성능 임계 근접, 잘못된 입력 | 임계치 초과 시 |
| error | 요청 실패, 의존성 장애, 데이터 불일치 | 즉시 또는 버킷 알림 |
| fatal | 프로세스 생존 불가 | 즉시 + 온콜 |
구조화를 해도 필드에 비밀번호·토큰·주민번호·카드 번호를 넣으면, 로그 저장소가 곧 비밀 저장소가 됩니다. 접근 권한이 개발 전원에게 열린 경우가 많아 시크릿 유출보다 범위가 넓을 수 있습니다. 환경변수 유출 방어는 시크릿·환경변수 체크리스트와 짝으로 보세요.
흔한 실수 — logger.info({ req }) 처럼 요청 객체 전체를 직렬화하면 헤더·쿠키가 그대로 들어갑니다. 명시 필드만 고르거나, 직렬화 전 redaction 플러그인(pino redact 등)을 기본 켜 두세요.
마이크로서비스가 아니어도 BFF → API → 큐 → 워커 한 줄은 흔합니다. 로그에 상관 ID가 없으면 타임스탬프 감으로 맞추게 됩니다. 트레이스와 이름을 맞추면 나중에 오픈텔레메트리 연동이 수월합니다.
구조화 로그는 필드가 늘수록 인덱스 비용이 늡니다. “전부 영구 보관”은 보통 불가능하고, 핫/웜/콜드 구간을 나눕니다. 숫자 목표는 팀 트래픽에 맞게 잡되, 체크리스트 항목은 공통입니다.
로그를 쌓기만 하고 알림이 없으면 장애는 고객 문의로 먼저 옵니다. 메트릭(프로메테우스 등)이 1차 신호이고, 로그는 “왜”를 파는 2차 도구인 경우가 많습니다. 스택 비교는 프로메테우스·그라파나 가이드를 참고하세요.
새 서비스·메이저 기능 배포 전에 아래만 통과해도 “로그가 안 잡혀서 롤백 판단 불가” 사고를 줄일 수 있습니다. PR 템플릿 체크박스로 옮기세요.
도구 선택 비교는 여기 범위 밖입니다. 다만 “기본값이 프로덕션에 위험한” 지점만 체크합니다.
redact.paths에 req.headers.authorization, req.headers.cookie를 기본 포함. Next.js 서버 로그와 엣지 런타임 제약이 다르면 경로별로 로거를 나눕니다.로컬에서는 pretty 출력이 편해도, CI e2e가 로그 문자열을 파싱하지 않게 하세요. 테스트 단언은 비즈니스 결과·메트릭으로 두고, 로그 포맷 스냅샷은 깨지기 쉽습니다.
프로덕션 경로에서는 구조화 로거로 통일하는 편이 맞습니다. 로컬 일회성 디버그는 괜찮지만, 머지 전에 제거하거나 로거 debug로 옮기는 습관을 PR 규칙에 넣는 것이 안전합니다. 남은 console은 레벨·필드 없이 수집기에서 파싱 실패·노이즈가 됩니다.
트래픽이 적으면 가능합니다. 초당 요청이 늘면 access 로그 성격은 샘플링하거나 메트릭(요청 수·지연 히스토그램)으로 옮기고, 로그는 예외·비즈니스 이벤트 중심으로 줄이는 편이 비용 대비 조사 효율이 좋습니다.
트레이싱을 아직 안 쓰면 request_id만으로도 충분합니다. 오픈텔레메트리를 도입하면 trace_id/span_id를 표준으로 두고, 기존 request_id는 외부 클라이언트 상관용으로 유지하는 이중 전략이 흔합니다. 이름만 섞이지 않게 문서에 매핑을 남기세요.
예외 경로에서만 스택을 직렬화하면 대부분 서비스에서 허용 범위입니다. 성공 경로마다 new Error().stack을 찍는 패턴이 비용이 큽니다. 에러 한 건에 스택 한 번, 그리고 동일 에러 버스트는 샘플링하거나 이슈 트래커로 올리는 구성을 권합니다.
이미 쓰는 클라우드 드레인·관측 스택에 맞추는 것이 우선입니다. 선택 기준은 일 수집량 가격, 보관 기간, 필드 검색 지연, 알림 연동, 팀 숙련도입니다. 도구를 바꿔도 필드 표준·redaction·레벨 정책이 있으면 이전이 쉽습니다.
관할·서비스 성격·로그에 식별자가 있는지에 따라 다릅니다. 설계 단계부터 로그에 직접 식별자를 넣지 않거나 해시만 두는 편이 대응이 쉽습니다. 법적 해석이 필요하면 내부 정책·전문가 확인이 필요하고, 아래 내용은 기술 체크리스트만 다룹니다.
