Mar 5, 2026

마지막 업데이트 Apr 14, 2026

Golang 트러블슈팅 가이드: timeout, goroutine, 런타임 장애를 어디부터 볼까

Go 서비스 장애는 “어떻게 고칠까”보다 “어느 축부터 봐야 하나”가 더 어렵습니다. timeout처럼 보여도 실제 원인은 goroutine 누수일 수 있고, goroutine 증가처럼 보여도 끝에서는 database pool 포화가 먼저일 수 있습니다.

이 글은 Go 운영 이슈를 증상 기준으로 빠르게 분기하기 위한 허브입니다. 아래 내용을 정리합니다.

지금 보이는 장애가 timeout 축인지, blocked work 축인지, 런타임 압박 축인지
첫 5분 안에 무엇을 보면 다음 글을 더 빨리 고를 수 있는지
비슷해 보이는 증상을 어떻게 구분할지

결론부터 말하면 Go 장애는 “가장 크게 드러난 사용자 영향”을 기준으로 첫 분기를 잡는 편이 가장 빠릅니다.

이 허브가 필요한 순간

context deadline exceeded가 반복된다
goroutine 수가 올라간 뒤 잘 내려오지 않는다
CPU보다 “일이 안 끝나는 느낌”이 더 강하다
트래픽이 줄어도 shutdown이 매끄럽게 끝나지 않는다
메모리, connection pool, queue가 함께 흔들려 어디부터 볼지 애매하다

이럴 때는 해결책을 먼저 찾기보다, 장애의 얼굴이 무엇인지부터 나누는 편이 더 빠릅니다.

첫 5분 체크

curl http://localhost:6060/debug/pprof/goroutine?debug=1
curl http://localhost:6060/debug/pprof/heap
curl http://localhost:6060/debug/pprof/profile?seconds=20

이 세 명령의 목적은 원인 확정이 아니라 첫 분기 선택입니다.

goroutine dump가 비정상적으로 길다: blocked work 또는 goroutine 축
CPU profile에서 특정 호출이 과열된다: timeout 또는 hot path 축
heap 쪽 신호가 먼저 튄다: 런타임 압박 축

먼저 묻는 질문

1. 요청이 느린가, 아니면 끝나지 않는가

느리기만 한 문제와 아예 빠져나오지 못하는 문제는 출발점이 다릅니다. 사용자에게 timeout이 보이면 deadline 쪽을 먼저 보고, 내부 worker가 걸려 보이면 goroutine 쪽을 먼저 봅니다.

2. 문제 범위가 요청 단위인가, 프로세스 전체인가

특정 API만 흔들리면 downstream latency나 timeout budget 문제일 가능성이 큽니다. 반대로 서비스 전체가 무겁고 둔해 보이면 memory, pool, shutdown 쪽이 먼저일 수 있습니다.

3. 증상이 트래픽과 함께 생겼는가, 트래픽이 빠진 뒤에도 남는가

트래픽이 줄어도 goroutine 수나 메모리가 회복되지 않으면 누수나 정리 실패 쪽일 가능성이 큽니다.

timeout 축으로 들어가야 할 때

아래에 가깝다면 외부 의존성의 응답 시간과 타임아웃 예산을 확인해 보는 편이 좋습니다.

외부 API, DB, RPC 경계에서 시간이 무너진다
재시도와 중첩 deadline이 겹쳐 의심스럽다
HTTP client timeout이 유독 많이 보인다
사용자 영향이 “느림”보다 “시간 초과”로 먼저 드러난다

goroutine 또는 blocked work 축으로 들어가야 할 때

아래에 가깝다면 Golang Goroutine Leak부터 가는 쪽이 낫습니다.

goroutine 수가 계속 쌓이고 복구가 느리다
channel receive 또는 send 대기가 길게 남는다
cancellation 또는 shutdown 경로가 깔끔하지 않다
background worker가 요청보다 오래 살아남는다

런타임 압박 축으로 들어가야 할 때

서비스 전체가 무겁고 불안정하다면 아래 글들이 더 잘 맞습니다.

이쪽은 timeout이나 goroutine보다 상위 레벨의 건강 상태를 보는 분기입니다. 메모리 압박, pool 포화, panic 전파, 종료 지연이 먼저 보인다면 이 축이 더 빠릅니다.

자주 하는 오진

timeout만 보여서 timeout 설정만 늘리는 경우

실제 원인이 blocked worker나 downstream stall이면 timeout을 키워도 장애만 길어집니다.

goroutine 수만 보고 무조건 누수라고 보는 경우

goroutine 증가 자체는 결과일 수 있습니다. upstream 지연이나 queueing 때문에 일시적으로 쌓이는 경우도 많습니다.

CPU가 높지 않아서 안심하는 경우

Go 장애는 CPU보다 blocked progress가 먼저 보이는 경우가 많습니다. “바쁘다”보다 “끝나지 않는다”가 더 중요한 신호일 수 있습니다.

아주 빠른 분기표

사용자에게 timeout이 가장 선명하다: deadline 글부터
goroutine 수와 blocked stack이 더 눈에 띈다: goroutine 글부터
메모리, pool, shutdown 문제가 먼저 보인다: 런타임 압박 글부터

그리고 첫 글 하나만 보고 끝내지 말고, 바로 인접 분기 한 개를 더 비교해 보는 게 좋습니다. 실제 운영 장애는 두 갈래가 겹치는 경우가 많기 때문입니다.

장애 조사 순서

사용자 영향이 timeout인지, stall인지, saturation인지 먼저 적습니다.
pprof로 goroutine, heap, CPU 셋 중 어느 축 신호가 가장 큰지 봅니다.
요청 경계 문제인지, 프로세스 전체 건강 문제인지 나눕니다.
가장 가까운 가이드 하나로 들어간 뒤, 인접 분기 글 하나를 바로 비교합니다.
증상 이름보다 “끝나지 않는 작업”, “사라진 시간”, “회복되지 않는 자원” 중 무엇이 핵심인지 정리합니다.

FAQ

Q. 이 글만 보면 문제를 해결할 수 있나요?

아니요. 이 글은 해결책 모음이 아니라 첫 분기를 빠르게 고르는 허브입니다.

Q. timeout과 goroutine 증가가 같이 보이면 어디부터 봐야 하나요?

사용자 영향이 더 직접적인 쪽부터 보세요. 고객이 timeout을 먼저 체감하면 deadline 글부터, 내부적으로 작업이 쌓이는 모습이 더 선명하면 goroutine 글부터 가는 편이 빠릅니다.

Q. Go를 막 배우는 사람도 읽어도 되나요?

기본 문법보다 운영 증상 분기에 가까운 글이라서, 실서비스 로그나 지표를 보고 있는 사람에게 특히 유용합니다.

먼저 읽어볼 가이드

검색 유입이 많은 핵심 글부터 이어서 보세요.