로그 레벨의 의미와 사용법 (FATAL부터 TRACE까지)

처리 결과에 맞는 로그 레벨을 정하고, 프로세스를 종료하는 API를 구분하고, 검색과 알림에 사용할 심각도를 정규화하는 방법을 설명합니다.

모범 사례
로그, 메트릭, 트레이스를 나타낸 그림

결제 서비스가 재고 조회 API를 호출했는데 첫 요청이 타임아웃됐습니다. 재시도는 성공했고 고객은 결제를 마쳤습니다. 첫 타임아웃은 남겨 둘 만한 정보입니다. 결제 실패를 조사할 때는 재고 조회의 개별 시도와 결제의 최종 결과를 구분해야 합니다. 재시도 한도까지 소진해 결제를 진행할 수 없다면, 해당 요청을 찾을 수 있는 정보와 함께 실패를 기록합니다.

로그 레벨은 이벤트의 심각도나 진단 정보의 상세도를 나타냅니다. 로거와 출력 핸들러는 이 값으로 로그를 걸러냅니다. 처리 결과를 알 수 있는 지점에서 레벨을 정한 뒤, 라이브러리와 수집기가 그 값을 어떻게 해석하는지 확인합니다.

처리 결과에 맞는 레벨을 정하기

흔히 쓰는 레벨 결제 서비스의 예
FATAL 필수 설정이 잘못되어 서비스가 시작되지 않는다.
ERROR 재시도 후에도 재고를 조회할 수 없어 결제에 실패했다.
WARN 첫 재고 조회가 타임아웃됐지만 재시도로 처리를 완료했다.
INFO 서비스가 시작되거나 정산 작업이 완료됐다.
DEBUG 조사 범위를 좁혀 재시도 판단과 소요 시간을 기록한다.
TRACE 이 레벨을 지원하는 프레임워크에서 계측한 재시도 루프의 각 분기를 확인한다.

이 표는 여섯 가지 이름을 사용하는 팀의 운영 예시입니다. 재시도로 복구되는 타임아웃이 자주 발생하면 건마다 경고를 남기는 것보다 재시도 횟수를 메트릭으로 집계하는 편이 추세를 보기 쉽습니다. 요청이 실패하면 최종 결과를 아는 계층에서 기록합니다. 모든 계층에서 ERROR를 남기면 고객이 겪은 한 건의 실패가 여러 오류 로그로 잡힙니다. 서비스와 작업 이름, 요청 ID 또는 트레이스 ID를 남기고, 원인 파악에 도움이 될 때 예외 정보를 첨부합니다. 자격 증명과 페이로드는 진단 필드에서 제외합니다. INFO 로그로 확인할 수 있는 범위는 해당 이벤트가 일어났다는 사실까지입니다.

로그 호출이 프로세스를 종료하는지 확인하기

Log4j 2는 FATAL부터 TRACE까지 여섯 가지 일반 이벤트 레벨을 정의합니다. Python 표준 logging의 최상위 기본 이벤트 레벨은 CRITICAL이며 FATAL은 그 별칭입니다. 기본 TRACE 레벨은 없습니다. Loguru에는 TRACE와 SUCCESS도 있습니다. 임곗값이나 쿼리를 작성하기 전에 사용 중인 라이브러리를 확인합니다. Log4j 2 레벨 · Python 로그 레벨 · Loguru 레벨

FATAL이라는 이름만으로는 호출 뒤에 프로세스가 종료되는지 알 수 없습니다. Python의 logging.fatal()은 critical()과 같은 방식으로 동작합니다. Go 표준 라이브러리의 log.Fatal()은 로그를 쓴 후 os.Exit(1)을 호출합니다. Pino의 fatal()은 종료 전 마지막 메시지를 기록하는 용도이며 해당 레벨이 활성화되어 있고 출력 대상에 flushSync()가 있으면 동기 플러시를 시도합니다. 실제 종료 여부는 애플리케이션 코드에서 정합니다. 시작 실패나 복구 가능한 요청 오류를 기록할 때는 해당 API의 동작을 확인하세요. Go log · Pino fatal

로거부터 출력 대상까지 필터 확인하기

Log4j 2의 일반적인 INFO 임곗값에서는 INFO, WARN, ERROR, FATAL이 레벨 검사를 통과할 수 있습니다. 이후 Appender나 별도의 필터가 이벤트를 제외할 수 있습니다. DEBUG 로그가 보이지 않으면 수집 경로를 조사하기 전에 로거와 출력 대상의 임곗값부터 확인합니다. 애플리케이션이 출력하지 않은 로그는 수집기가 복구할 수 없습니다.

평소 로그에 필요한 소요 시간이 없다면 대상 모듈이나 인스턴스에서만 DEBUG 또는 TRACE를 임시로 켜고 종료 시각을 정합니다. 출력 대상과 수집기에는 기존 필터가 그대로 남아 있을 수 있습니다. 필요한 로그가 민감한 값 없이 도착하는지 확인합니다. 런타임에 로그 레벨 변경하기

원래 레벨을 보존하면서 정규화하기

숫자의 의미는 형식에 따라 달라집니다. RFC 5424 syslog의 심각도는 Emergency가 0, Debug가 7입니다. OpenTelemetry의 정규화된 SeverityNumber는 숫자가 클수록 심각하며 WARN은 13–16입니다. SeverityText에 원래 레이블을 보존할 수 있습니다. syslog의 Warning 값 4와 OpenTelemetry의 4는 뜻이 다르므로, 여러 시스템을 함께 검색하기 전에 소스별로 매핑합니다. RFC 5424 심각도 · OpenTelemetry 로그 데이터 모델

예를 들어 Pipeline에서 결제 서비스의 WARN을 Guance의 warning으로 매핑하면 다음과 같은 레코드가 나옵니다. 원래 레이블은 별도 필드에 남겨 둡니다.

{"service":"checkout","operation":"check_inventory","outcome":"recovered","level":"WARN","status":"warning"}

DataKit 로그 수집기 문서에서는 레벨을 추출하지 못했을 때의 기본값을 info로 설명하고, 표시할 때는 trace와 verbose를 debug로 묶습니다. DataKit 로그 수집 가이드(영어)에는 unknown으로 대체된다는 설명도 있습니다. 탐지 규칙을 만들기 전에 경고 레코드와 레벨이 없는 레코드를 실제 수집 경로에 넣고 저장된 status를 확인합니다. SECURITY처럼 이벤트 유형을 나타내는 레이블은 분류 필드에 따로 보존하면 유형과 심각도를 각각 검색할 수 있습니다.

Guance 로그 탐색기에서 서비스와 정규화된 status로 필터링하면 탐지 규칙이 집계할 레코드를 확인할 수 있습니다. 재시도로 복구된 요청은 추세를 추적하는 데 쓰고, 결제 실패에는 별도의 임곗값과 알림 경로를 설정할 수 있습니다. 오류 로그가 늘었다고 고객 영향으로 판단하기 전에 실패 건수를 트래픽이나 서비스 수준 목표와 비교합니다. Guance 로그 탐지 · 로그 모니터링

맞춤형 플랜 상담

문의하기

커뮤니티 가입

WeChat으로 스캔하여
커뮤니티에 가입하세요

Guance 사용해 보기

온라인에서 바로 시작하고 사용한 만큼만 결제하세요.

시작하기

Guance 요금제 선택

코드 저장소