[CORE-010][실무] 오류 메시지와 로그로 원인 찾기 > IT 기술 공유

• 목록

[이번 수업]
감으로 코드를 고치면 원인을 가리기 쉽습니다. 오류 메시지, 스택 트레이스, 로그를 증거로 삼아 증상 기록→가설→최소 재현→수정 확인 순서로 문제를 좁혀 봅니다.

[선수지식]
터미널에서 Python을 실행할 수 있어야 합니다. 예외는 정상 흐름을 계속할 수 없을 때 보내는 오류 신호입니다.

[학습목표]
1. 오류와 스택 트레이스에서 조사 지점을 찾습니다.
2. 수준과 필드를 갖춘 로그를 남깁니다.
3. 한 조건씩 바꾸며 가설을 검증합니다.

[핵심개념]
오류 메시지는 실패한 동작과 예외 종류를 알립니다. 스택 트레이스는 예외까지 호출된 함수와 파일 위치를 보여 줍니다. 마지막 줄의 예외 종류와 메시지를 읽고, 그 위에서 내가 작성한 파일의 가까운 줄을 찾습니다.

로그는 실행 사건을 시간순으로 남긴 기록입니다. Python의 수준은 DEBUG, INFO, WARNING, ERROR, CRITICAL입니다. 차례로 개발 세부 정보, 정상 흐름, 확인할 상황, 작업 실패, 서비스 지속이 위험한 상황에 씁니다. 모든 일을 ERROR로 남기면 중요한 신호가 묻힙니다.

실무에서는 시간, 수준, event 이름, request_id, 버전, 상태를 검색 가능한 필드로 둡니다. request_id는 한 요청의 여러 로그를 잇습니다. OpenTelemetry도 Timestamp, Severity, Body, Resource, Attributes, TraceId 등을 정의합니다. 동시에 발생한 사건이 반드시 인과관계인 것은 아니므로 정상 요청과 비교합니다.

증상·시각·환경·버전·입력을 기록하고 마지막 예외와 최초 실패 지점을 찾습니다. 관련 로그를 모아 가설 하나를 세운 뒤 안전한 최소 입력으로 재현합니다. 한 조건만 바꾸고 수정 후 같은 절차와 주변 기능을 다시 확인합니다.

[따라하기]
다음을 log_demo.py로 저장합니다. 표준 라이브러리만 사용합니다.

```python
import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s level=%(levelname)s request_id=%(request_id)s %(message)s",
)
logger = logging.getLogger("demo")

def divide(total, people):
    return total / people

request_id = "demo-001"
try:
    print(divide(120, 0))
except ZeroDivisionError:
    logger.exception("계산 실패", extra={"request_id": request_id})
```

macOS/Linux는 `python3 log_demo.py 2> error.log`, Windows PowerShell은 `py log_demo.py 2> error.log`를 실행합니다. 기본 로그 출력인 표준 오류를 `2>`로 저장합니다. macOS/Linux는 `cat error.log`, PowerShell은 `Get-Content error.log`로 봅니다. 시각·경로·줄 번호를 뺀 예상 결과는 다음과 같습니다.

```text
... level=ERROR request_id=demo-001 계산 실패
Traceback (most recent call last):
...
ZeroDivisionError: division by zero
```

마지막 줄에서 0으로 나눈 증상을 보고, 위쪽의 log_demo.py 위치에서 `divide(120, 0)`을 찾습니다. people을 4로 바꾸면 `30.0`이 나오고 ERROR는 사라집니다.

[흔한 실수]
문구 일부만 검색하고 예외 종류·버전·조건을 남기지 않거나 여러 설정을 동시에 바꾸면 원인을 확인할 수 없습니다. 재현되지 않으면 정상과 실패 실행의 입력, 버전, 환경 변수 이름, 시각부터 비교합니다.

[보안 주의]
비밀번호, API 키, 세션·쿠키, 토큰, 전체 개인정보는 로그에 남기지 않습니다. 외부 입력의 줄바꿈과 제어 문자를 정리해 로그 주입을 막습니다. 상세 스택 트레이스는 접근 통제된 저장소에 두고 권한·보존 기간·암호화를 정합니다. 실습은 본인 소유의 로컬 또는 허가된 격리 환경에서만 수행합니다.

[직접 해볼 과제]
people이 0 이하이면 `logger.warning`을 남기고 계산하지 않도록 바꿔 보세요. 0과 4를 넣어 WARNING과 정상 결과를 확인하되 비밀값은 기록하지 않습니다.

[확인문제]
1. 오류 메시지·스택 트레이스·로그의 역할은 어떻게 다른가요?
2. 여러 서비스의 로그에서 같은 요청을 잇는 데 어떤 필드가 필요한가요?
3. 운영 로그에 비밀번호나 토큰을 남기면 안 되는 이유는 무엇인가요?

[다음 학습]
다음 과정 CS-010에서는 시간·공간 복잡도와 병목을 다룹니다. CORE-011에서는 공식 문서로 해결책을 검증합니다.

[공식 참고 자료]
- Python Logging HOWTO: https://docs.python.org/3/howto/logging.html
- Python traceback 공식 문서: https://docs.python.org/3/library/traceback.html
- OpenTelemetry Log Data Model: https://opentelemetry.io/docs/specs/otel/logs/data-model/
- NIST SP 800-92 로그 관리 가이드: https://nvlpubs.nist.gov/nistpubs/legacy/SP/nistspecialpublication800-92.pdf
- RFC 5424 Syslog Protocol: https://www.rfc-editor.org/rfc/rfc5424.html
- OWASP Logging Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html