마이크로서비스 로깅 모범 사례: 서비스 간 요청 추적하기

로그 형식과 이벤트 시각을 통일하고 중복 수집을 줄이며, OpenTelemetry와 Guance로 요청의 로그와 트레이스를 연결하는 방법을 알아봅니다.

모범 사례
여러 서비스의 로그가 한 곳에 모이는 모습을 그린 그림

결제 요청이 시간 초과로 끝났다. 게이트웨이에는 오류가 남았지만, 결제 서비스는 잠시 뒤 승인을 마쳤다. 게이트웨이 로그의 전송이 지연되어 결제 로그가 저장소에 먼저 도착했다. 도착 시각으로 정렬하면 전송 순서는 알 수 있다. 요청을 조사하려면 각 이벤트가 발생한 시각과 같은 요청의 기록을 찾을 단서가 필요하다.

마이크로서비스 로그를 설계할 때는 팀이 공통 이벤트 형식을 쓰도록 하고, 각 로그의 수집 경로를 정한다. 요청과 관련된 기록에는 로그를 쓸 때의 활성 트레이스 컨텍스트를 넣는다. 그다음 용도에 맞춰 보존 기간과 열람 권한을 정한다.

발생 시각과 관측 시각을 분리한다

저장소를 고르기 전에 공통 필드부터 정한다. 이벤트 시각은 UTC의 RFC 3339처럼 시간대 오프셋이 명시된 형식으로 기록한다. 서비스 이름, 환경, 릴리스 버전을 유지하고 이벤트 이름과 로그 수준의 기준을 맞춘다. 호스트 시계를 동기화하더라도 오차가 남을 수 있으므로 여러 서비스의 이벤트 순서를 판단할 때 이를 고려한다.

다음은 합성 요청에 대해 애플리케이션이 출력하는 JSON 로그 한 줄이다. 로거는 기록을 작성할 때 활성 Span에서 ID를 가져올 수 있다.

{"event_time":"2026-10-01T12:00:00.425Z","service":"payments","env":"production","version":"1.8.4","severity":"INFO","event":"payment.completed","event_id":"evt_payment_01","trace_id":"4bf92f3577b34da6a3ce929d0e0e4736","span_id":"00f067aa0ba902b7"}

OpenTelemetry 로그 데이터 모델은 이벤트 발생 시각인 Timestamp와 수집 시스템이 이벤트를 관측한 시각인 ObservedTimestamp를 구분한다. Body, 심각도, 발생 주체인 Resource, 선택적인 트레이스 컨텍스트도 각각 별도 필드다. JSON 로그를 OpenTelemetry 레코드로 바꿀 때는 서비스와 배포 정보를 Resource 속성에 매핑하고, 가능하면 원래 로그 수준 표기와 정규화한 심각도 번호를 함께 보존한다. 위 JSON은 애플리케이션 로그 형식이다. OTLP 페이로드 형식은 별도로 확인한다. OpenTelemetry 로그 데이터 모델(영어)

Guance에서는 로그 Pipeline으로 이벤트 시각을 time에, 로그 수준을 status에 매핑할 수 있다. 시각과 시간대, 수준을 이미 아는 샘플을 보내 저장된 값이 맞는지 확인한다. 파서가 도착 시각을 사용하면 늦게 온 로그가 조사 시간 범위에서 벗어날 수 있다.

각 로그 스트림은 한 경로로 수집한다

Kubernetes에서는 노드 수집기가 컨테이너 런타임에 기록된 애플리케이션 표준 출력과 표준 오류를 읽을 수 있다. 사이드카는 배치 방식이다. 예를 들어 애플리케이션 파일을 읽어 전송하거나 자체 표준 출력으로 내보낼 수 있다. 같은 이벤트를 두 경로가 읽으면 저장소에 두 번 도착할 수 있으니, 한 경로를 담당으로 정한 후 다른 수집기를 설정한다. Kubernetes 로깅 아키텍처(영어)

백엔드가 배치를 받았는데 응답이 유실되면 재시도로 동일한 이벤트가 다시 들어올 수 있다. 중복 제거가 필요한 경우 발생 지점에서 이벤트마다 안정적인 ID를 부여하고, 수신 측에 처리 규칙을 둔다. 한 트레이스에 서로 다른 로그가 여럿 있으므로 트레이스 ID를 중복 제거 키로 쓰면 개별 이벤트까지 사라진다. OTLP 중복 데이터 제약(영어)

Guance에서 일반 로그 인덱스를 여러 개 쓰는 경우, 보존과 접근 요구사항에 따라 분류 기준을 정한다. 규칙으로 분류하는 로그는 조건에 처음으로 맞는 일반 인덱스에 기록된다. 순서를 바꾸기 전에 두 규칙에 동시에 맞는 샘플로 저장 위치를 확인한다. 저장 경로와 열람 권한은 따로 점검한다.

활성 트레이스 컨텍스트를 로그에 기록한다

게이트웨이에서 발급한 요청 ID는 애플리케이션에서 요청을 찾는 데 쓸 수 있다. 트레이스 ID는 분산 트레이스 전체를, Span ID는 그 안의 개별 작업을 식별한다. 요청 ID와 트레이스 ID를 모두 쓴다면 별도 필드에 넣는다.

요청을 받을 때 들어온 트레이스 컨텍스트를 추출하고, 다음 서비스에 요청할 때 지원되는 헤더나 메시지 속성에 주입한다. 로그에는 활성 Span의 trace_id와, 있으면 span_id를 기록한다. OpenTelemetry의 비 OTLP 로그 규약에 따르는 JSON에서는 소문자 16진수로 트레이스 ID는 32자리, Span ID는 16자리다. 트레이스 밖에서 발생한 로그에는 해당 필드를 생략한다. 수집기가 레코드를 받았다는 사실만으로 누락된 애플리케이션 컨텍스트가 복원되지는 않는다. 비 OTLP 로그의 트레이스 컨텍스트(영어) · OpenTelemetry 컨텍스트 전파

로그나 트레이스에서 요청을 따라간다

결제 사례에서는 서비스와 시간 범위로 트레이스를 찾고, 이상이 발생한 Span을 확인한다. 같은 트레이스 ID로 로그를 찾은 뒤 Span ID가 있다면 결제 시도의 로그까지 좁힌다. 게이트웨이 로그부터 봤다면 기록에 들어 있는 트레이스 ID로 반대 방향으로 조회한다. 게이트웨이 시간 초과와 결제 성공은 한 요청에서 모두 발생할 수 있다. 이벤트 시각과 Span 간 관계를 함께 비교한다.

Guance 트레이스 상세의 관련 로그는 기본적으로 trace_id를 사용한다. 트레이스의 service, env, version 등을 바탕으로 설정된 매핑에서 조회할 로그 인덱스를 선택한다. 아는 로그가 나오지 않으면 그 인덱스를 직접 조회하고 저장된 필드 값을 트레이스와 비교한다. 로그와 트레이스가 모두 수집되어 조회 가능한 상태여야 한다. 트레이스 샘플링에 따라 로그는 남고 트레이스가 없을 수도 있다.

필요한 로그만 안전하게 보관한다

기록해도 되는 필드를 정의하고, 비밀번호와 액세스 토큰, 원본 결제 정보는 로그에서 제외한다. 유지해야 할 값은 해당 값을 볼 필요가 없는 저장소에 도착하기 전에 마스킹하거나 제거한다. 정상 입력 외에 형식이 깨진 입력과 여러 줄 샘플도 테스트한다. 파싱된 필드는 마스킹되어도 원본 본문에 값이 남을 수 있다. 열람과 내보내기 권한을 제한하고 설정 변경을 감사한다. Guance 인덱스의 감사 화면에서는 해당 인덱스의 작업 기록을 볼 수 있다. OWASP 로깅 가이드(영어) · Collector에서 민감 데이터 마스킹

보존 기간은 조사에 필요한 기간, 적용되는 요구사항, 비용을 바탕으로 정한다. 아카이브로 옮기기 전에 필요한 기록을 다시 꺼내 검색할 수 있는지 시험한다. 단기 진단 로그와 감사 로그의 보존 기간은 서로 달라도 된다.

서비스 메시가 프록시 텔레메트리를 만들더라도 ‘결제 요청을 보냈다’ 같은 업무 이벤트는 애플리케이션이 남긴다. 우선 게이트웨이에서 결제 서비스까지 요청 하나를 보내고, 각 단계의 발생 시각과 저장된 ID, 인덱스를 확인한다. 그다음 다른 요청 경로에 적용한다.

관련 글 · 로그 모니터링

맞춤형 플랜 상담

문의하기

커뮤니티 가입

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

Guance 사용해 보기

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

시작하기

Guance 요금제 선택

코드 저장소