운영 장애 로그를 볼 때는 ERROR 문자열 전체를 훑기보다 발생 시간대, 서비스, 요청 ID 또는 실행 ID로 범위를 먼저 좁히는 편이 좋습니다. 같은 메시지가 반복돼도 서로 다른 요청일 수 있고, 마지막 오류가 최초 원인은 아닐 수 있습니다.
이 글에서 바로 찾기 5개 항목
조사 전에 세 가지를 고정합니다
- 시간대: 서버 로그의 UTC·한국 시간 등 표기를 확인하고 장애 시각 전후 구간을 잡습니다.
- 식별자: API는 requestId·traceId, 배치는 jobExecutionId와 stepName을 확보합니다.
- 범위: 어느 서버·컨테이너·배포 버전의 로그인지 확인합니다. 여러 인스턴스의 시간을 섞지 않습니다.
원본 로그를 편집하거나 비우지 마세요. 사용자 정보·토큰·쿠키·요청 본문이 포함될 수 있으므로 외부에 전달할 때는 필요한 구간만 추리고 민감값을 가립니다.
일반 텍스트 로그에서 앞뒤 문맥까지 찾기
다음은 GNU grep이 있는 Linux 환경의 읽기 전용 예제입니다. app.log와 식별자는 실제 값으로 바꾸세요. 큰 파일 전체를 내려받기 전에 보존 위치와 접근 권한부터 확인합니다.
grep -n -F -C 4 -- 'jobExecutionId=12345' app.log
grep -n -E -- 'ERROR|Exception|Caused by:' app.log첫 명령은 일치한 행과 앞뒤 네 행을 보여 줍니다. 두 번째 명령은 예외 후보를 찾는 보조 수단입니다. 여러 요청이 섞인 파일에서는 식별자가 없는 스택 트레이스가 이웃 요청의 것일 수 있으므로 시간·스레드·서비스 정보를 함께 대조하세요.
JSON 로그는 문자열 검색보다 필드로 좁힙니다
아래는 실측 장애가 아니라 출력 형식을 설명하기 위한 예시입니다. 한 행에 JSON 객체 하나를 저장하면 jq 같은 파서로 필드를 정확히 선택할 수 있습니다.
{"timestamp":"2026-09-18T01:12:00Z","level":"ERROR","service":"batch-worker","jobExecutionId":12345,"stepName":"exportStep","errorCode":"REMOTE_TIMEOUT","message":"Remote response timeout"}이 형식의 app.jsonl 파일과 jq가 준비되어 있다면 다음 명령으로 특정 배치 실행만 출력할 수 있습니다. 셸 문법은 Bash 기준입니다.
jq -r 'select(.jobExecutionId == 12345) |
[.timestamp, .level, .stepName, .errorCode, .message] | @tsv' app.jsonl예시 행의 예상 출력은 시간, ERROR, exportStep, REMOTE_TIMEOUT, 메시지 순입니다. 실행 ID를 문자열로 기록하는 시스템이면 비교값도 "12345"로 맞춰야 합니다. JSON이 아닌 행이 섞여 파싱에 실패했다면 이를 조용히 버리지 말고 입력 형식을 먼저 확인하세요. 필터 구문은 jq 공식 매뉴얼에서 확인할 수 있습니다.
오류를 찾은 다음에는 가설을 분리합니다
| 발견한 단서 | 추가 확인 |
|---|---|
| Timeout | DNS 조회·연결·TLS·상대 응답 중 어느 단계인지 확인합니다. 상대 요청이 실제로 처리됐는지도 대조합니다. |
| Unique constraint | 업무 유일 키와 재시도 기록을 확인합니다. 중복 실행인지 정상 중복 거절인지 구분합니다. |
| 시작 로그만 있고 종료 로그가 없음 | 프로세스 생존, 로그 수집 누락, 메타데이터 상태를 확인합니다. 특정 단계가 원인이라고 즉시 단정하지 않습니다. |
API 호출이 DNS 단계에서 지연된다면 dig로 재귀·권한 DNS를 나눠 확인하는 절차가 도움이 됩니다. 배치의 실패 실행을 찾았다면 JobExecution과 StepExecution 조회로 넘어가세요.
재발 방지를 위한 로그 필드
메시지를 더 많이 남기기보다 추적에 필요한 필드를 일정하게 유지합니다. 타임스탬프와 시간대, 서비스·배포 버전, 요청/실행 ID, 단계, 결과 코드, 소요 시간을 구분해 기록하세요. DEBUG를 운영 전체에 무기한 켜는 대신 필요한 범위와 기간을 정합니다.
로그 로테이션과 보존 기간도 함께 관리해야 합니다. 로그가 남지 않았다는 이유만으로 일이 일어나지 않았다고 단정하지 말고, 수집 실패·시계 오차·샘플링 여부를 확인하세요.
조사가 끝났을 때는 “무슨 오류가 있었다”에서 멈추지 않습니다. 최초 이상 시각, 영향을 받은 대상, 확인한 원인과 아직 남은 가설, 복구 후 정상 동작 근거를 남겨야 다음 장애에서 같은 탐색을 반복하지 않습니다.