시스템이 다운되었습니다. 로그가 왜 그런지 설명해야 합니다.

Source: Dev.to

위의 링크에 있는 전체 텍스트를 제공해 주시면, 해당 내용을 한국어로 번역해 드리겠습니다. (코드 블록이나 URL은 그대로 유지됩니다.)

소개

이전 기사에서 나는 거의 논의되지 않는 점을 제시했다: 잘못된 로그는 프로덕션 버그만큼 위험할 수 있다.
무언가가 실패하면 팀의 첫 번째 움직임은 로그를 살펴보며 답을 찾는 것이다. 그러나 대부분의 경우 로그는 그 역할을 수행하지 못한다: 지나치게 상세하고, 프레임워크가 생성한 방대한 스택 트레이스를 포함하며, 일반적인 메시지와 유용한 맥락이 부족하다. 정보는 존재하지만 실행 가능하지 않아, 잡음을 걸러내는 데 시간 낭비와 문제를 재현해야 하는 필요성을 초래한다.

로그가 중요한 이유

• 운영 증거: 로그는 단순한 기술 출력이 아니라, 발생한 일에 대한 신뢰할 수 있는 증거 역할을 합니다.
• 개발자를 위한 것이 아니라 시스템이 스스로 설명하기 위한 것: 사고가 발생했을 때, 사람들은 코드가 어떻게 작성됐는지보다 무슨 일이 일어났는지 알고 싶어 합니다.
• 도구가 아니라 품질: 명확한 기준이 없으면 사용된 도구와 관계없이 쓸모없는 로그가 생성됩니다.

기존 패턴

가장 간단하고 널리 채택되는 모델은 다음과 같습니다:

• 5W + H – 무엇, 어디서, 언제, 누가, 왜, 어떻게.
• Event + Context + Outcome – 이벤트, 컨텍스트 및 결과.

OpenTelemetry 및 Elastic Common Schema와 같은 패턴은 동일한 아이디어를 강화합니다: 로그는 구조화되고, 컨텍스트가 제공되며, 추적 가능해야 합니다. 좋은 로그는 이벤트를 설명하고, 충분한 컨텍스트를 제공하며, 결과를 명확히 표시하고, 상관관계를 가능하게 합니다.

로그에서 분석해야 할 항목

1. 흐름을 재구성할 수 있나요?
   시작, 중간, 끝을 이해할 수 있나요? 로그의 구멍은 관측성의 사각지대입니다.

2. 충분한 컨텍스트가 있나요?
   orderId, paymentId, userId와 같은 식별자는 조사에 필수적입니다.

3. 메시지가 명확한가요?
   “처리 오류”와 같은 일반적인 메시지는 아무것도 설명하지 못합니다. 로그를 이해하려면 코드를 열어야 한다면 로그가 실패한 것입니다.

4. 심각도 수준이 적절한가요?

   • INFO → 정상적인 흐름 관련
   • WARN → 제어된 예상치 못한 동작
   • ERROR → 영향을 미치는 실패

   잘못된 수준은 시스템의 해석을 왜곡합니다.

5. 추적 가능성이 있나요?
   traceId 또는 correlationId는 서비스 간 흐름을 따라갈 수 있게 해줍니다. 이것이 없으면 각 로그는 고립된 조각이 됩니다.

6. 핵심 포인트가 로그에 기록되어 있나요?

   • 외부 연동
   • 상태 변화
   • 중요한 결정
   • 재시도 및 폴백

7. 시스템이 스스로 설명하고 있나요?
   로그가 시스템이 수행한 작업을 보여주나요?

   • 다시 시도했나요?
   • 폴백했나요?
   • 중단했나요?

8. 영향에 대한 시각이 있나요?

   • 작업이 중단되었나요?
   • 데이터가 일관되지 않나요?
   • 사용자에게 영향을 주나요?

9. 노이즈가 있나요?
   과도한 로그는 로그가 부족한 것만큼 방해가 됩니다.

10. 민감한 데이터가 노출되고 있나요?
    비밀번호, 토큰, CPF, 카드 정보 등은 로그에 나타나면 안 됩니다.

QA가 로그를 평가해야 하는 위치

코드 리뷰

리뷰는 개발자가 수행하지만, QA는 로그 기준이 충족되는지 확인해야 합니다:

• 중요한 포인트가 로그에 기록되어 있나요?
• 충분한 컨텍스트가 제공되나요?
• 메시지가 명확한가요?

테스트

개발 (통합 및 단위)

• 관련 시나리오에서 로그가 생성되나요?
• 내용이 정확한가요?
• 불필요한 로그가 있나요?

더 통합된 레벨 (E2E 및 API)

• 로그가 동작을 설명하는 데 도움이 되나요?
• 흐름을 연관시킬 수 있나요?
• 문제를 재현할 필요성을 없애나요?

인시던트

• 로그가 도움이 되었나요, 아니면 방해가 되었나요?
• 사각지대가 있었나요?

실제 문제

• 각 개발자는 서로 다른 방식으로 로그를 남깁니다.
• 각 서비스는 서로 다른 이야기를 기록합니다.
• 각 사고는 수동 조사로 이어집니다.

간단한 질문

다시 시스템을 실행하지 않고도 무슨 일이 일어났는지 이해할 수 있나요?

답이 아니오라면, 품질에 문제가 있습니다.

마무리

로그는 기술적인 세부 사항, 디버그 또는 선택 사항이 아니다. 시스템의 필수적인 부분이며 그에 따라 다루어져야 한다. 그렇지 않으면 필요할 때 그 역할을 수행하지 못한다.