구조화 로그란? 필드와 발생 시각을 맞춰 조회하기
로그 필드의 타입과 발생 시각을 정하고, 기존 형식을 정규화한 뒤 서비스별로 오류를 조회하는 방법을 알아봅니다.
결제 오류가 늘어 “connection refused”를 검색했더니 여러 서비스의 로그가 나옵니다. 조사에 필요한 정보는 더 구체적입니다. 어느 서비스가 이 로그를 남겼는지, 오류 코드가 같은지, 처리 중 얼마 만에 실패했는지를 알아야 합니다.
구조화 로그는 이런 정보를 각각의 필드에 담습니다. 사람이 메시지를 읽을 수 있고, 백엔드가 필드를 추출하고 매핑한 뒤에는 쿼리로 서비스별 집계나 처리 시간 필터링도 할 수 있습니다. JSON은 흔히 쓰는 인코딩 형식입니다. 텍스트 한 줄을 JSON으로 감싸기만 하면 필요한 정보는 여전히 메시지에서 추출해야 합니다.
쿼리할 수 있는 이벤트 하나부터 시작하기
다음은 정규화한 합성 로그입니다. 결제 실패 한 건을 나타냅니다.
{
"time": "2026-08-25T08:55:01Z",
"status": "error",
"message": "database connection failed",
"service": "order",
"event": "checkout.failed",
"error_code": "DB_CONNECT_ERROR",
"duration_ms": 1200,
"trace_id": "00000000000000000000000000000001"
}
메시지는 사람에게 실패 내용을 설명합니다. event와 error_code는 문구가 바뀌어도 같은 조건으로 검색할 수 있게 해 줍니다. duration_ms는 숫자입니다. 생산자가 문자열 "1200"을 보낸다면, duration_ms > 900처럼 숫자로 비교하기 전에 수집 단계에서 타입을 확인하거나 변환합니다. 스키마에는 필드의 의미와 타입, 단위, 값이 없을 때의 처리 방식을 정해 둡니다. 값이 없는 상태를 유지하면 실제 측정값이 0인 경우와 구분할 수 있습니다.
이벤트가 발생한 시각과 수집기가 관측한 시각을 분리합니다. 버퍼링 때문에 로그가 2분 늦게 도착해도 유효한 발생 시각이 있다면 장애 당시를 조회할 수 있습니다. 수집 지연을 조사할 때는 관측 시각도 따로 남겨 둡니다. OpenTelemetry의 Timestamp와 ObservedTimestamp가 이 두 시각에 해당합니다. OpenTelemetry 로그 데이터 모델(영어)
로그를 만드는 곳에서 필드로 출력하기
수집기가 처리할 수 있는 형식을 정하고 로거가 해당 형식으로 출력하도록 설정합니다. 타입이 있는 값이나 중첩 데이터에는 JSON을 쓸 수 있습니다. 단순한 키와 값에는 Logfmt도 적합합니다. 개발과 운영에서 다른 형식을 쓴다면 두 수집 경로를 각각 확인합니다.
다음 예제는 Go 1.21 이상 표준 라이브러리로 동작합니다. log.go로 저장한 뒤 go run log.go를 실행합니다.
package main
import (
"log/slog"
"os"
)
func main() {
logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
logger.Error("database connection failed",
"service", "order",
"event", "checkout.failed",
"error_code", "DB_CONNECT_ERROR",
"duration_ms", 1200,
)
}
JSON 핸들러는 이벤트 필드와 함께 time, level, msg를 한 줄에 출력합니다. 시각은 프로그램을 실행한 때의 값이며, 이 독립 실행 예제에는 활성 트레이스가 없습니다. 앞의 스키마에 맞추려면 수집 시 level과 msg를 status와 message로 매핑하고, 로그 레벨 값도 정규화합니다. Go slog 문서(영어)
인프라 구성 요소도 같은 기준으로 확인합니다. PostgreSQL 15 이상에서 log_destination에 jsonlog를 사용하려면 서버 시작 시 적용되는 logging_collector를 켜야 합니다. 출력 형식을 바꾸기 전에 파일 경로와 로테이션, 수집기 설정을 확인합니다. PostgreSQL 로그 설정(영어)
기존 형식을 수집 단계에서 정규화하기
수정하기 어려운 서비스가 일정한 형식의 텍스트를 남긴다면 Guance Pipeline(영어)으로 발생 시각, 레벨, 업무 필드를 추출할 수 있습니다. 정상 줄과 필드가 비어 있는 줄, 형식이 깨진 줄을 각각 시험합니다. 데이터 정책이 허용하는 범위에서 조사에 필요한 원문을 남기고, 파싱이 실패했음을 알 수 있게 합니다. 설정을 적용한 뒤 Pipeline을 통과한 로그가 대상입니다. 이미 저장된 기록은 별도로 이전하거나 두 형식을 모두 처리할 수 있는 쿼리로 조회합니다.
함께 조사할 서비스부터 같은 의미와 타입을 사용합니다. 뷰어가 중첩 JSON을 펼쳐 보여 주더라도, 내부 필드로 집계하려면 추가 추출이나 매핑이 필요할 수 있습니다. 로그 인덱스 규칙으로 저장 위치와 보존 기간을 관리합니다. Guance 로그 인덱스
정규화한 필드로 집계하기
다음 DQL은 수집기가 source=checkout을 설정하고, 정규화한 로그를 default 인덱스로 보내며, time을 이벤트 발생 시각으로 파싱했다고 가정합니다.
L("default")::checkout:(count(*) AS error_events)
{ `status` = "error" AND `event` = "checkout.failed" }
[1787648100000:1787648400000] BY service
조회 구간은 2026년 8월 25일 08:55~09:00 UTC입니다. 실제 데이터에서는 수집 소스와 인덱스, 시간을 맞춰야 합니다. 위의 합성 로그만 조건에 맞으면 order의 건수는 1입니다. 재시도로 로그가 여러 건 남을 수도 있고 이 이벤트 없이 실패하는 요청도 있으므로, 이 값은 오류 로그 건수입니다. 요청 오류율은 집계 대상 요청의 총수가 정의된 지표로 계산합니다. Guance DQL 레퍼런스
Guance 로그 탐색기에서 추출된 필드를 확인하고 인덱스에서 검색 가능한 필드로 범위를 좁힙니다. 선택한 범위의 메시지를 군집화하면 유사한 로그에서 살펴볼 예를 고르기 쉽습니다. 총수나 추세가 필요하면 조건을 명시해 집계하고, 알림이 필요하면 모니터를 설정합니다.
로그를 트레이스와 연결하는 맥락 남기기
요청에 활성 트레이스 컨텍스트가 있으면 실제 트레이스 ID를 기록합니다. 특정 작업을 식별해야 한다면 스팬 ID도 함께 남깁니다. 애플리케이션 요청 ID는 트레이스 ID와 별개의 식별자입니다. Guance 트레이스 상세의 트레이스 전체 로그는 기본적으로 trace_id를 사용해 연결합니다. service, env, version 등의 필드는 로그 인덱스를 고르는 데 쓰입니다. 두 신호가 모두 수집되고 보존 기간 내에 있어야 하며, 조회 권한도 필요합니다.
메시지는 읽기 쉽게 유지하고 조사에 필요한 필드만 추가합니다. 자격 증명과 불필요한 개인정보는 로그에서 제외합니다. 스키마를 넓히기 전에 실제 부하에서 직렬화와 파싱, 저장 비용을 확인합니다. 먼저 같은 장애를 여러 서비스에서 올바른 발생 시각과 필드 조건으로 찾을 수 있는지 시험해 보세요.
