로그 포맷 모범 사례: JSON, 타임스탬프, 추적 ID

운영 로그를 검색할 수 있도록 JSON 이벤트 경계, 발생 시각, 로그 레벨, 트레이스 ID와 민감한 필드의 출력 범위를 정합니다.

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

UTC 03:14에 결제 요청이 타임아웃됐다고 가정해 보겠습니다. 게이트웨이는 라우트와 밀리초 단위의 응답 시간을 남겼습니다. 결제 서비스는 업스트림 타임아웃 메시지와 스택 트레이스를 여러 줄에 나눠 썼습니다. 두 로그 모두 저장소에 도착했지만 라우트로 검색할 수 있는 쪽은 하나뿐입니다. 스택은 여러 이벤트로 쪼개졌고, 두 기록을 이어 줄 ID도 서로 다릅니다.

로그 포맷은 이벤트의 경계와 조회에 사용할 필드를 정합니다. JSON을 선택해도 스키마는 따로 맞춰야 합니다. 한 서비스가 duration_ms를 숫자로 보내고 다른 서비스가 "900ms"라는 문자열을 보내면 같은 조건으로 집계하기 어렵습니다.

한 건의 로그가 어디서 끝나는지 정하기

자유 형식 텍스트는 개발 중에 프로세스 하나를 따라갈 때 읽기 좋습니다. 반구조화 로그는 일정한 접두어나 키-값 구문을 사용합니다. 구조화 로그는 필드와 타입을 미리 정합니다. 같은 타임아웃을 남겨도 수집할 때 필요한 처리가 달라집니다.

형식 기록 예시 수집 시 필요한 처리
자유 형식 Upstream timed out after 900 ms 메시지에서 시간과 단위를 추출
반구조화 level=ERROR duration_ms=900 msg="Upstream timed out" 키-값 구문과 따옴표 규칙에 맞춰 파싱
구조화 {"level":"error","duration_ms":900,"message":"Upstream timed out"} JSON을 파싱하고 정해 둔 스키마에 맞춤

파일이나 표준 출력을 한 줄씩 수집한다면 JSON 인코더로 한 줄에 객체 하나를 기록합니다. 메시지 안의 따옴표, 역슬래시, 줄바꿈은 이스케이프해야 합니다. 들여쓰기를 넣은 여러 줄짜리 JSON을 전송하려면 별도의 이벤트 구분 방식이 필요합니다. 개발 콘솔에서는 보기 쉬운 형식을 쓰고 운영 로그에서는 같은 이벤트 필드를 JSON으로 남길 수 있습니다. JSON 문자열과 이스케이프

Go의 slog.JSONHandler는 이벤트마다 JSON 한 줄을 출력합니다. Nginx에서는 log_format에 JSON 객체 구조를 정의하고 변수 값에 escape=json을 적용한 뒤, access_log에서 그 형식을 선택합니다. PostgreSQL 15 이상에서 log_destination = 'jsonlog'를 사용하려면 logging_collector도 켜야 합니다. 소스마다 필드가 다르므로 실제 출력부터 확인한 뒤 공통 스키마로 매핑합니다. Go slog · Nginx 로그 모듈 · PostgreSQL 로깅 설정

로그 레벨과 이벤트 발생 시각 맞추기

조회에 사용할 레벨을 debug, info, warning, error처럼 정의하고 소스의 값과 매핑합니다. 의미가 같은 WARN과 warning은 같은 필터로 찾아야 합니다. 숫자 레벨은 라이브러리마다 다릅니다. OpenTelemetry의 SeverityNumber에도 자체 척도가 있으며 문자열인 SeverityText와 별도입니다. OpenTelemetry 로그 데이터 모델

장애를 조사할 때 기준으로 삼는 시각은 이벤트가 발생한 때입니다. RFC 3339 형식에는 Z나 UTC 오프셋을 넣습니다. 유닉스 타임스탬프를 사용한다면 초, 밀리초, 나노초 중 어떤 단위인지 스키마에 명시합니다. 관측 또는 수집 시각을 알 수 있다면 다른 필드에 남깁니다. 전송이 30초 늦어도 실제 타임아웃이 발생한 시간대로 검색할 수 있어야 합니다. UTC로 통일해도 호스트 시계의 오차까지 사라지지는 않습니다. RFC 3339

검색 범위를 좁힐 수 있는 필드 남기기

모든 이벤트에서 서비스와 환경을 식별할 수 있게 합니다. 레플리카를 구분해야 한다면 인스턴스 ID를 추가합니다. 릴리스 버전이나 커밋은 로그 본문 또는 수집 후에도 조회할 수 있는 리소스 속성에 둡니다. 두 버전이 동시에 트래픽을 받는 배포 중에는 타임아웃이 어느 버전에 몰리는지 확인할 수 있습니다. 파일, 함수, 행 번호는 조사에 필요한 경로에 한해 로거나 핸들러에서 추가합니다.

라우트는 /orders/{order_id} 같은 템플릿으로, 경과 시간은 숫자형 duration_ms로 남깁니다. 서비스 간에 이름, 타입, 단위를 맞춥니다. 주문 ID나 HTTP 헤더 이름을 필드명으로 사용하면 필드가 계속 늘어납니다. 식별자는 고정된 필드의 값으로 기록하고, 생산자가 필드를 빼거나 타입을 바꿨을 때 파서가 어떻게 처리하는지도 확인합니다.

요청 ID와 트레이스 ID 구분하기

애플리케이션의 request_id로 같은 값을 전달받아 기록한 컴포넌트의 로그를 조회할 수 있습니다. 트레이스 ID는 분산 트레이스 전체, 스팬 ID는 그 안의 특정 작업을 가리킵니다. 현재 스팬이 있으면 계측 라이브러리에서 ID를 가져와 로그에 넣고, 다음 서비스로 트레이스 컨텍스트를 전파합니다. 활성 스팬이 없는 경로에서는 요청 ID를 사용할 수 있습니다. 검색 범위는 저장소에 도착한 로그와 보존 기간으로 제한됩니다. 연결하려는 트레이스도 샘플링이나 보존 정책에 따라 없을 수 있습니다. W3C Trace Context

다음 합성 이벤트는 JSON 한 줄입니다. 스택의 줄바꿈을 이스케이프해서 같은 이벤트 안에 담았습니다.

{"time":"2026-11-09T03:14:00Z","level":"error","service":"payments","env":"prod","version":"v2.3.1","route":"/orders/{order_id}","duration_ms":900,"request_id":"req-example-42","trace_id":"4bf92f3577b34da6a3ce929d0e0e4736","span_id":"00f067aa0ba902b7","message":"Upstream returned \"timeout\"","error_type":"UpstreamTimeout","stack_trace":"UpstreamTimeout\n  at capture (payments.go:71)"}

호출 경로가 중요한 예외에 스택을 붙입니다. 견적 유효 기간 만료처럼 예상 가능한 업무상 거절은 오류 코드와 필요한 컨텍스트만으로 충분할 수 있습니다. 파일이나 함수별로 집계하려면 스택 프레임을 필드로 나눕니다. 기존 로거에서 스택을 일반 텍스트 여러 줄로 기록한다면, 수집기에 이벤트 첫 줄을 지정하고 이어지는 줄이 원래 오류와 함께 묶이는지 확인합니다. DataKit 멀티라인 로그 수집

프로세스 밖으로 나갈 필드 정하기

객체를 로그에 넘기기 전에 허용할 필드를 정합니다. 사용자 객체 전체나 요청 본문, 헤더 맵보다 범위가 정해진 오류 유형과 조사에 필요한 식별자를 우선합니다. Go에서는 slog.LogValuer를 구현해 해당 값이 로거에서 어떤 형태로 출력될지 지정할 수 있습니다. 다른 포매터나 오류 문자열, 원본 메시지, 스택에 민감한 값이 남을 수 있으므로 직렬화 결과도 확인합니다. OWASP 로깅 지침(영어)

배포 전에는 정상 이벤트, 따옴표와 줄바꿈이 있는 예외, 필드가 빠진 이벤트를 같은 파서에 넣어 봅니다. Guance에서는 DataKit으로 파일을 수집하고 Pipeline에서 애플리케이션 레벨을 status에 매핑할 수 있습니다. 로그 화면에서 파싱된 발생 시각과 필드 타입을 살펴보고 원본 메시지에 민감한 값이 남았는지 확인합니다. APM과 로그 수집이 모두 설정돼 있다면 추출한 trace_id를 조회 가능한 트레이스와 대조합니다. DataKit 로그 수집기 · Guance 로그와 트레이스 연결(영어)

포맷이 정해졌다면 로그 집계에서 여러 시스템의 로그를 한곳으로 모으는 방법을 확인할 수 있습니다. 전반적인 접근 방식은 구조화 로깅 안내(중국어 간체)에 나와 있습니다.

맞춤형 플랜 상담

문의하기

커뮤니티 가입

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

Guance 사용해 보기

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

시작하기

Guance 요금제 선택

코드 저장소