문제를 추적하는 로그 기록의 기본

프로젝트를 진행하며 신입 개발자 입장에서 로그 코드를 작성하는 것이 번거롭다고 느껴지거나, 로그를 남겨야 하는 이유가 와닿지 않을 수 있다는 생각이 들어 ‘문제를 추적하는 로그 기록의 기본’이라는 주제로 블로그를 작성하게 되었습니다. 신입 개발자의 관점에서 이해하기 쉽도록 소프트웨어 개발 및 운영에 필요한 로그에 대해 기본적인 접근 방식을 먼저 살펴보려 합니다. </br></br>

1. 로그를 남겨야 하는 이유

로그는 시스템 운영과 문제 해결에 있어 매우 중요한 역할을 합니다. 사용자나 시스템에서 발생하는 모든 활동을 기록함으로써, 서비스 장애나 보안 이슈 발생 시 원인 분석과 해결책을 제공할 수 있습니다. 적절한 로그 관리 없이는 트러블슈팅이 어려워지고, 서비스 신뢰성의 하락으로 이어질 수 있습니다.

사용자 문의를 로그로 분석하면 시스템 오류로 인한 문제부터 단순한 착오로 발생한 경우까지 다양한 원인을 확인할 수 있습니다. 시스템 오류가 발생했다면 신속하게 해결하고, 사용자 착오로 인한 문의에는 정확한 설명을 제공하여 서비스의 신뢰도를 유지하는 것이 중요합니다.

쉬운 이해를 위하여 서비스 장애부터 사용자 단순 불편 문의까지, 로그를 활용해 분석할 수 있는 내용과 간단한 실제 사례들을 몇 가지 소개해보겠습니다. </br></br>

2. 로그를 통한 문제 추적과 해결 예시

2.1. 사용자 로그인 문제

  • 문제: 사용자가 로그인 시도가 되지 않는다고 문의
  • 로그 활용:
    • 로그인 시도 시간, IP, 로그인 시도 횟수, 비밀번호 실패 메시지를 로그에서 확인
    • 사용자가 올바른 인증 정보를 입력했는지, 아니면 계정이 잠금 상태인지 파악하여 해결
    • 로그인 시 발생한 오류 메시지를 통해, 백엔드 시스템의 장애를 점검
  • 실제 로그 분석 사례:
    • 접속이 제한된 국가에서 여러 번 해킹 시도로 인해 로그인이 잠긴 상태
    • 제한된 횟수 이상으로 잘못된 비밀번호로 접속을 시도하여 로그인이 잠긴 상태
    • 사용자의 계정이 ‘사용안함(비활성화)’ 처리되어 있던 사례

2.2. API 호출 실패

  • 문제: 외부 시스템과의 API 연동이 실패
  • 로그 활용:
    • API 요청 및 응답 로그를 통해 어떤 데이터가 들어갔고, 어떤 응답이 왔는지 확인
    • API 호출이 실패한 원인을 정확히 파악하기 위해, 요청 시 전달된 파라미터와 응답 코드(예: 500, 404)를 기록
    • 특정 API 서버가 다운되었거나, 요청이 잘못된 형식으로 전달되었는지 등을 확인
  • 실제 로그 분석 사례:
    • 외부 시스템 API의 접속 정보, 연동을 위한 데이터가 변경되었으나, 안내 누락으로 설정 및 코드에 반영되지 않아 연동 오류가 발생한 사례
    • 전달된 파라미처 확인 시 필수 데이터를 누락한 채로 API 연동을 시도한 사례

2.3. 서비스 접속 장애 문제

  • 문제: 사용자가 서비스에 접속할 수 없다고 문의
  • 로그 활용:
    • 접속 시도 시간 등의 정보를 전달 받은 후, 어떤 시스템 레벨에서의 문제인지 로그에서 확인
  • 실제 로그 분석 사례:
    • 사용중인 DNS 서버가 Ddos 공격을 받아 DNS 연결에 문제가 생긴 경우
    • 메모리 사용률이 높은 메서드를 단시간에 여러 번 호출하여 OutOfMemory로 인한 WAS 다운 (사양 변경이 어려운 On-promise 서버 사용중인 업체의 레거시 코드로 작성된 서비스에서 종종 발생하는 문제였습니다.)
    • 로그 분석 시 서비스 내부에는 문제가 없었으나, 데이터 센터 화재로 인한 클라우드 장애 여파로 일부 시스템에 연결되지 못해 서비스 접속 장애로 이어진 기록이 발견됨

2.4. 메일 발송 장애

  • 문제: 메일을 발송할 수 없다고 문의
  • 로그 활용:
    • 메일 발송 시간, 수신자 등의 정보를 받아 로그에서 문제 확인
  • 실제 로그 분석 사례:
    • 수신자가 업무용 메일주소를 사용하는 경우, 수신자 메일 서버의 DNS 이용 기간 만료로 DNS 조회 실패하여 발송 실패
    • 발신자가 클라이언트(Outlook 등) 사용 시 발신메일 서버, 포트, 보안 설정 등을 잘못한 경우

2.5. 파일 업로드 오류

  • 문제: 사용자가 파일을 업로드할 수 없다고 문의
  • 로그 활용:
    • 파일 업로드 요청 시 전송된 파일의 크기, 파일 타입, 요청 IP 등을 기록한 로그를 분석
    • 업로드 서버의 상태와 디스크 공간을 체크하여, 서버에 용량 부족이 아닌지 확인
    • 파일 업로드 도중 발생한 오류 메시지를 기록하여, 파일 형식 문제나 서버의 처리 오류를 확인
  • 실제 로그 분석 사례:
    • 파일 업로드 경로로 설정된 디스크의 공간이 꽉 차 더 이상 쓰기 처리가 불가능
    • 내부 네트워크 작업 여파로 파일 업로드 경로로 설정된 NAS 접속 장애 </br></br>

3. 로그 수준 (Log Level)

로그는 단순히 데이터를 남기는 것이 아니라, 중요도와 상세도를 구분하는 방식이 필요합니다. 이를 통해 로그의 우선순위를 정리하고, 필요한 정보만 추출하여 효율적으로 로그를 활용할 수 있습니다. 효과적인 로그 관리를 위해서는 목적에 맞는 로그 수준을 설정하고, 필요한 내용을 선택적으로 기록하는 것이 중요합니다.

  • DEBUG: 개발과 디버깅 과정에서 사용합니다. 함수의 입력 값, 반환 값, 내부 상태 등을 기록하여 문제를 정확하게 추적할 수 있습니다.
  • INFO: 시스템의 정상적인 동작 로그입니다. 예를 들어, 서비스가 시작되었거나 정상적으로 종료된 경우 등에 기록됩니다.
  • WARN: 시스템에 문제가 발생할 가능성이 있는 경우, 예기치 않은 동작을 나타내는 경고 메시지를 기록합니다. 예를 들어, 외부 API 응답 시간이 길어진 경우 등을 기록할 수 있습니다.
  • ERROR: 시스템에서 실제 오류가 발생했을 때의 로그입니다. 오류의 원인과 상태를 파악하는 데 중요한 정보를 담고 있어, 빠르게 문제를 해결하는 데 유용합니다.
  • FATAL: 치명적인 오류가 발생하여 시스템이 더 이상 정상적으로 작동할 수 없을 때 기록하는 로그입니다. 즉각적인 조치가 필요한 상황을 나타냅니다. </br></br>

4. 로그 기록의 Best Practice

4.1. 구체적이고 명확한 메시지 작성

문제 발생 시 오류 원인을 빠르게 파악할 수 있도록 함수명, 입력 값, 발생 시간 등을 포함해 기록한다.

4.2. 관련된 컨텍스트 정보 포함

요청 ID, 세션 정보 등 문제 해결에 필요한 관련 데이터를 함께 남긴다.

4.3. 일관성 있는 로그 포맷

로그 형식을 통일하면 분석과 문제 해결이 쉬워진다.

4.4. 불필요한 로그 최소화

DEBUG 로그는 개발 환경에서만 사용하고, 운영 환경에서는 INFO·ERROR 수준으로 제한한다.

4.5. 중앙화된 로그 관리

로그 분석 도구를 활용해 여러 시스템의 로그를 통합 관리하고 실시간 모니터링을 가능하게 한다. </br></br>

5. 마무리

문제 해결을 위한 로그 기록은 소프트웨어 개발과 운영에서 필수적입니다. 로그 코드가 충분히 작성되지 않거나, logback 설정 등이 제대로 되어있지 않은 경우 추후 유지보수 담당자가 슬픈 상황에 놓이게 될 수 있습니다 ㅠ.ㅠ 체계적인 로그 관리를 통한 신속한 장애 대응은 시스템 안정성과 성능 유지 도움이 되고, 이것이 곧 서비스의 신뢰도로 직결된다는 점을 항상 고려하여 로그 코드를 작성하면 좋을 것 같습니다. 감사합니다.