트러블 슈팅 템플릿

문제가 발생했을 때 그 원인을 찾아 제거하는 트러블 슈팅에 대해서 알아보고, 반복적이거나 비슷한 문제 해결을 도와주는 트러블 슈팅 문서를 작성하는 법을 고민하고, 고민에 기반하여 생성된 템플릿을 공유합니다.

들어가며

우리는 문제를 만나고, 문제를 해결하면서 살아갑니다. 어떤 문제를 처음 겪으면 당황하겠지만 끝내 그 문제를 해결하고, 다시 그 문제를 만난다면 이전에 문제를 해결했던 경험을 통해 예전보다는 휠씬 수월하게 넘어가죠. 문제가 반복적으로 발생해서 해결 방법이 익숙하다면 그 문제를 더 이상 문제라고 보지 않게 됩니다.

예를 들어 우리가 난생 처음 매운 음식을 먹었다면, 입 안에서 타오르는 이 감각을 어떻게 해결할지 몰라 당황스럽겠지만 물이나 우유를 마시거나, 매운 음식이 무엇인지 인지하고 다시는 먹지 않는 방식으로 이 문제를 해결합니다. 그 원인이 무엇이고 어떻게 해결하면 되는지 알게 된 것이죠. 우리는 이를 “경험" 이라고 부릅니다.

개발자는 새로운 기술, 기술 간 의존성, 외부 환경 등 수 많은 요인들로 항상 문제를 겪게 됩니다. 끝없는 이슈의 향연 속에서 이슈를 해결해가면서 경험을 쌓으며 문제 해결 능력을 기르게 됩니다. 많은 회사가 경력자를 더 선호하는 것은 서비스 개발 도중에 겪을 이슈를 이미 경험해서 문제를 빠르게 해결해 줄 수 있는 사람을 기대하기 때문이겠지요.

경험은 양보다 밀도가 중요하다

하지만 경력이 길다고 그 사람의 문제 해결 능력이 우수하다고 판단하기는 어렵습니다. 10년 동안 비슷한 일만 해왔다면 그 사람이 경험한 문제는 한정되어 있고, 당연히 문제 해결 능력도 한정적일 수 밖에 없습니다. 단순히 일을 얼마나 오랫동안 해왔는지가 아니라, 얼마나 다양하고 밀도 있는 문제를 경험하고 해결해왔는지가 더욱 중요한 것이죠.

우리는 문제가 발생하면 과거의 경험을 현재 문제에 대입해보면서 문제를 해결하게 되는데요. 코드로 한번 표현해보면 다음과 같지 않을까요?

Problem problem = new Problem();
List<ProblemSolution> solutions = MySolution.list();

for (solution : solutions) {
    if (solution.match(problem)) {
        problem.solve(solution);
        break;
    }
}

기억은 휘발성인거 아시죠?

그런데 이러한 경험이 자신의 기억 속에만 존재한다면, 우리는 언젠가 힘들게 얻었던 소중한 경험을 잃어버릴 수 있습니다. 뿐만 아니라 컨디션에도 영향을 받게 되죠. 머리가 안 돌아가는 그런 날, 누구나 한번 쯤은 있잖아요? 네, 기억 속에 있는 것은 한계가 있습니다. 슬프지만 우리의 뇌는 계속해서 노후화되어 갑니다. 기억은 영원할 수 없어요. 휘발성 메모리인 우리 뇌보다 더 좋은 저장소가 있습니다. 바로 문서입니다.

트러블 슈팅이 필요한 이유

발생한 문제를 해결하는 과정을 담을 문서는 여러 이름으로 불리는데요. 지금 당장 기억나는 것은 포스트모템(postmortem), 장애 리포트(Incident Report), 그리고 지금 설명하고자 하는 트러블 슈팅(Trouble Shooting)이 있습니다. 사실 문서의 이름이 크게 중요한 것은 아니지만, 제 각 문서에 느낌적인 느낌을 말씀드리면 포스트모템과 장애 리포트는 발생한 문제가 이미 제품 품질에 영향을 미친 이 후에 작성한 문서로 최대한 작성하지 않는게 좋은… 문서구요. 물론 장애가 최대한 발생하지 않는게 좋다는 의미입니다. 가장 나쁜 것은 장애가 발생했는데도 아무런 회고 없이 그냥 넘어가버리는 것이죠. 반면 트러블 슈팅은 개발하면서 겪는 문제 해결 방법을 작성하거나, 장애는 아니지만 현재 시스템이 가진 문제를 정의하고 그 문제점을 해결하는 과정에서 적는 문서라고 볼 수 있죠. 리서치하는 느낌이 든다고 할까요…?

트러블 슈팅 문서는 다음과 같은 이유로 필요합니다.

기억은 휘발성, 문서는 비휘발성

위에서 언급했지만, 우리의 기억이 완벽하지 않기 때문입니다. 아마 적어도 세 번은 같은 이슈를 겪어야 기억이 날거예요, 우리는 아래와 같은 말을 자주 하죠. (적어도 저는 자주 합니다 😂)

예전에 이 문제 어떻게 해서 해결 했었는데…

겪은 문제와 해결 과정을 검색을 지원하는 도구에 잘 기록해 놓으면 (Notion, Confluence, Wiki 같은) 열심히 구글링해서 찾은 문서보다 더 든든한 지원군이 되어줄거예요.

공유는 언제나 옳다

같은 문제로 삽질하고 있는 동료를 위해 작성해야 합니다. 같은 기술 스택에서 동일한 도메인으로 개발하고 있는 동료는 나와 같은 문제에 직면해 있을 확률이 높습니다. 열심히 삽질해서 이슈를 해결하면 그 이슈는 이미 동료가 예전에 해결했던 경험 다들 있으실거예요. 저는 같은 이슈로 세 번이상 질문을 받으면, 그 때 간단하게 문제와 해결 방법을 적어서 공유해왔는데요. 아무래도 매번 부연 설명을 반복적으로 하게 되더군요. 그래서 처음부터 트러블 슈팅 과정을 적어가면 휠씬 효율적이겠다고 생각했고, 그 생각이 이 문서를 작성하는 이유이기도 합니다.

또한 트러블 슈팅 문서를 작성하여 동료에게 공유하면 여러 시각으로 문제 해결 방법을 볼 수 있게 됩니다. 각 개발자들은 보유하고 있는 역량들이 서로 다르기 마련인데요. 오랫동안 고민해도 해결 방법을 못 찾는 문제를 누군가는 자신이 가지고 있는 경험이나 지식으로 더 좋은 방법을 조언해 줄 수 있죠. 아래서 설명할 트러블 슈팅 문서에 “문제 정의" 와 “사실 수집" 만 잘 작성해 놓으면, 이 후 문서는 함께 작성할 수 있습니다.

우리는 보통 혼자 일하지 않습니다. 동료들을 돕거나 도움을 받으세요. 공유는 그러기 위한 좋은 시작점이며, 공유는 언제나 옳습니다.

트러블 슈팅 템플릿이 필요한 이유

제가 프로젝트를 진행하면서 작성한 문서를 보다 보면, 애플리케이션 로그만 잔뜩 복사해놓은 문서를 심심치 않게 볼 수 있는데요. 아마 당시에 발생한 문제를 해결하기 위해서 필요한 로그를 저장해놓은 것일텐데 나중에 보면 이게 무슨 문제를 해결하기 위해서 저장해놓은 로그인지, 그래서 이 이슈는 해결했는지 파악하기가 불가능하더군요.

이런 문서는 옳지 않다고 생각한 뒤로 에러 메시지나 앱 로그 말고도 추가적인 진행 상황을 기록해 놓았는데, 작성할 때마다 그 양식이 제각각이였습니다. 아마 그 당시에 의식의 흐름대로 작성하다보니 정형화되어 있지 않은 것이죠. 어떤 문제를 해결하기 위해서 가장 보편적인 접근 방법을 가이드 해 줄 수 있다면, 문제의 해결점을 찾는데 도움이 되지 않을까? 라는 생각에 여러 문서를 참고하였습니다.

트러블 슈팅 템플릿

노션으로 작성한 템플릿 문서도 함께 공유합니다.

문제 정의

명확한 문제 정의는 올바른 해결책을 찾기 위해 반드시 필요합니다. 이슈 티켓 링크로 대체할 수 있습니다.

사실 수집

오류 메시지, 이벤트 로그, 문제 해결 프로세스에 도움이 될 수 있는 스크린샷, 비디오, 진단 결과, 모니터링 결과 등 문제가 발생한 원인을 추론하기 위한 근거 자료가 될 수 있는 정보를 수집합니다.

원인 추론

정의된 문제와 수집된 사실을 바탕으로 원인을 추론합니다. 먼저 문제의 가장 일반적인 원인부터 작성하세요. 더 복잡한 것을 원인으로 판단하기 전에 명백하고 단순한 것부터 고려하세요. 가설을 세우고 테스트하여 원인을 한개씩 제거하며 정확한 원인을 결정할 수 있습니다.

해결 방안 수립

추론된 원인을 해결하기 위한 방안을 나열합니다. 해결 가능성이 높은 순서로 기재하거나 가장 빠르고 쉬운 것부터 시작할 수도 있습니다.

조치 및 구현

수립된 해결 방안을 실제로 조치합니다. 조치한 방법이나 해결을 위한 깃허브 이슈 또는 깃 커밋을 링크해도 좋습니다.

결과 관찰

이슈가 해결되었는지 관찰 하고 해결되지 않았다면, 원인 추론 또는 해결 방안 수립 단계에서 다시 진행합니다.

문서 작성

문제가 해결되었다면 문서를 마무리합니다.

마치며

돌이켜보면 참 많은 문제를 만났고, 그 문제를 해결해왔음에도 작성해 놓은 문서가 별로 없어서, 지금까지는 기억의 저편에 있는 경험을 열심히 끌어올려 업무를 진행해왔네요. 앞으로 만나는 이슈들은 차곡차곡 잘 쌓아서 저에게도 도움이 되고 다른 누군가에게도 도움이 되었으면 좋겠습니다. 더 좋은 템플릿이 있다면 알려주세요. 긴 글 읽어주셔서 감사합니다.