디버그
비용이 많이 드는 실수는 첫 번째로 그럴듯한 원인을 고치는 것입니다. 처음 몇 분은 패치하는 것이 아니라 범위를 좁히는 데 사용하세요.
방법
- 정확한 실패를 캡처하세요. 전체 오류 텍스트, 스택 추적, 종료 코드, 타임스탬프, 요청 ID, 실행된 명령어를 코드 블록에 넣으세요. 오류를 요약하면 중요한 하나의 토큰을 잃게 됩니다.
- 재현하세요. 즉시 트리거할 수 있는 가장 작고 빠른 방법을 찾으세요. 재현할 수 없다면 그렇게 말하고 로그를 기반으로 작업하세요. 조용히 추측하지 마세요.
- 무엇이 변경되었는지 확인하세요.
git log --since, 최근 배포, 의존성 업데이트, 설정 또는 IAM 변경, 제공자 업그레이드, 만료되는 인증서 등. 대부분의 사고는 변경에서 발생합니다. - 두세 가지 가설을 세우고 가능성과 확인 비용에 따라 순위를 매기세요. 테스트하기 전에 적어두세요.
- 한 번에 하나의 가설을 테스트하고, 해당 가설이 사실인 경우에만 영향이 있을 변경으로 테스트하세요. 도움이 되지 않은 것은 되돌리세요. 추측성 편집을 축적하지 마세요.
- 원인을 수정하세요. 그런 다음 수정 없이는 실패하는 회귀 테스트를 작성하세요(
tdd스킬 참조). - 재현했던 것과 동일한 방식으로 검증하고, 더 넓은 테스트 모음을 실행하세요.
증상별 확인할 곳
| 증상 | 첫 번째 확인 사항 |
|---|---|
| 로컬에서는 작동하고 CI에서 실패 | 환경 변수, 시크릿, OS/아키텍처, node/python 버전, 캐시된 의존성, 시간대, 작업 디렉터리 |
| 간헐적 / 불안정 | 테스트 간 공유 상태, 시간, 순서, 네트워크, 실제 실패를 숨기는 재시도 |
| AWS AccessDenied | 어떤 주체(aws sts get-caller-identity), 리소스 정책 vs ID 정책, SCP, 권한 경계, KMS 키 정책, 리전 |
| Lambda 타임아웃 / 콜드 스타트 | VPC 연결, DNS, 핸들러 외부 초기화, 메모리 크기, X-Ray의 다운스트림 지연 시간 |
| Terraform 오류 | 제공자 버전, 상태 드리프트(terraform plan -refresh-only), -target 잔재물, 잠금 파일 |
| Kubernetes 파드 준비 안 됨 | kubectl describe pod, 이벤트, 프로브, 리소스 제한, 이미지 가져오기, 시크릿/configmap 마운트 |
| 배포 후 5xx | 이전 이미지/커밋 비교, 상태 확인 경로, 환경/설정 차이, DB 마이그레이션 순서 |
규칙
- 코드를 읽기 전에 로그를 읽으세요. 로그는 위치를 알려주고, 코드는 이유를 알려줍니다.
- 필요한 경우 임시 로깅을 추가하고 커밋하기 전에 제거하세요.
- 재시도되는 내용을 이해하지 않고 권한을 넓히거나, TLS 검증을 비활성화하거나, 예외를 잡아서 삼키거나, 재시도를 추가하여 '수정'하지 마세요.
- 수정했으면 한 문단으로 원인, 왜 발견되지 않았는지, 다음 번에 이를 방지할 방법을 기록하세요. 그 문단은 PR 또는 커밋 본문에 포함됩니다.