원칙적 접근은 온갖 시련으로부터 우리의 마음을 안전하게 지켜준다. 이 글은 문제의 원인을 파악하고 해결하는 과정에서 원칙을 세우고 기록하며 일을 처리할 때 얻는 이점에 대한 이야기다. 트러블슈팅을 소재로 하여 작성되었지만, 꼭 트러블슈팅이 아니더라도 원칙적 접근과 기록은 다양한 일에 적용할 수 있다는 점을 강조하고 싶다.

필자가 트러블슈팅 업무 중에 삽질을 거듭하면서 세운 원칙과 기록의 중요성에 대해 느낀점을 공유하려 한다. 틈만 나면 못살게 구는 이슈들을 해결하며 어려움을 느끼고 있을 개발자들에게 더 와닿을 만한 내용이다. 물론 우리가 처한 상황이 이 글의 내용과는 거리가 있을 수 있다. 필자가 궁극적으로 하고 싶은 말은 원칙적 접근과 기록의 중요성이라는 것을 기억하길 바란다.

트러블슈팅이란?

운영 중인 시스템에서 예상치 못한 문제가 발생하여 사용자에게 좋지 않은 경험을 제공하게 됐을 때, 문제 발생의 원인을 분석하여 문제점을 파악하고 해결하는 과정을 통틀어 트러블슈팅이라 한다. 복잡한 상황일지라도 문제의 원인을 정확하게 파악하여 근본적인 원인을 제거하는 것이 중요하다. 우리는 문제가 해결되었음을 적절한 근거를 바탕으로 설명할 수 있어야 한다.

업무 프로세스의 파악

가장 먼저 해야 할 일은 자신이 속한 조직의 업무 프로세스를 파악하는 일이다. 당연한 말이지만 효율적인 방안을 찾기 위해서는 기존에 일 처리를 어떻게 하고 있는지 알아야 한다. 팀 내에 문서화 된 자료가 있는지 찾아보고, 만약 없다면 동료들에게 물어보는 게 가장 빠르다.

내부적으로 서버를 직접 운영해야 하는 On-Premise 형식의 솔루션을 여러 고객사에 제공 중인 대기업 B2B 회사의 경우로 하나의 예를 들어보겠다. (고객사 – 기술 지원 담당자 – 개발자)

1. 고객사에 구축된 시스템에서 이슈가 발생한다.
2. 고객사에서 기술 지원 담당자에게 해당 이슈를 보고한다.
3. 기술 지원 담당자가 해결할 수 있는 이슈는 직접 해결한다.
4. 해결하지 못했거나 로그 분석, 코드 수정 등 개발자의 기술력이 필요한 이슈는 개발자에게 넘어온다.
   (이 때 분석에 필요할 만한 자료를 함께 주는데, 실제로는 별 도움이 되지 않을 때도 있다.)
5. 개발자는 기술 지원 담당자를 통해 고객사와 간접적으로 소통하며 문제를 해결한다.

고객사마다 개별적인 서버를 운영해야 하므로 운영 환경이 모두 다르다. 고객사의 로그, 환경 등을 파악하려면 고객사에게 자료를 요청하거나 PC 원격 제어, 방문 등의 방법으로 직접 접근하는 수 밖에 없다. 그래서 요청하거나 고객사 PC에 접근할 때 최소한의 횟수로 효율적이고 정확하게 처리할 수 있도록 신중을 기해야 한다.

고객사의 요청에 가장 먼저 응하는 기술 지원 담당자는 고객사와 개발자 사이에서 다리 역할을 한다. 개발자는 고객사와 직접적으로 소통하지 않고 담당자를 통해 간접적으로 소통한다. 개발자가 기술 지원 담당자에게 문제 해결에 필요한 정보를 요청하면 기술 지원 담당자가 확보하여 개발자에게 전달해주는 식이다. 이런 처리 방식으로는 치명적인 이슈가 아니면 일의 진행이 매우 느려지기도 한다. 자연스럽게 우선 순위에 따라 일을 처리할 수 있게 되는 장점도 있다. 급하거나 불가피할 때에는 개발자가 고객사에 직접적으로 접근하여 문제를 해결할 수도 있어 꽤 유연한 일 처리가 가능하다.

효율적인 커뮤니케이션을 위해

원활한 의사소통을 위해서 고객과 협업하는 동료의 기술적 지식 수준을 파악하는 것도 중요하다. 상대방의 눈높이에 맞추어 이해하기 쉽게 말할 수 있어야 한다. 지나치게 자세하거나 추상적인 설명을 하게 되면 의도와는 다르게 전달될 수 있다. 그러면서 발생할 수 있는 시간 낭비를 줄여야 한다. 글을 작성했다면 전달하기 전에 텍스트 만으로 쉽게 이해할 수 있는 내용인지 한 번 생각해 보는 것도 도움이 된다. 그림을 그리면 쉽게 설명할 수 있는 내용을 너무 어렵게 전달하려 하는 건 아닌지 생각해보는 습관을 들이자.

트러블슈팅이 어려운 이유

입사 이후 해결해야 할 이슈를 처음 할당 받았을 때가 떠오른다. 기술 지원 담당자가 처음 전달해준 자료는 원인을 분석하기에 부족한 상황이었다. 어디서부터 시작해야 할 지 몰라서 동료들에게 물어보았다. 일반적으로 우선 해당 이슈의 영향 범위를 파악한 후, 분석에 필요한 자료를 다시 요청하는 방식으로 진행한다고 했다.

그렇게 확보한 자료에 문제의 원인이 고스란히 담겨있어 쉽게 문제를 해결할 수 있다면 다행이다. 그렇게 해서 모든 문제가 해결되면 참 좋겠다. 하지만 이슈에 따라서 각양각색의 상황이 펼쳐진다는 점이 트러블슈팅의 어려운 점이다.

만약 로그 파일을 확보할 수 없거나 현상을 쉽게 재현할 수 없다면 어떻게 해야 하는가? 심지어 이슈가 터진 부분에 로깅 코드가 작성되지 않아 로그가 아예 남지 않았다면 어떻게 해야 할까? 우리는 생각하지 못했던 다양한 상황을 준비되지 않은 채로 갑자기 마주하게 된다. 경험을 쌓는 과정에서 여러 가지 상황에 대처할 수 있도록 나만의 원칙을 명시적으로 세워두는 것이 다음에 비슷한 일을 처리할 때 큰 도움이 된다.

원칙과 기록이 주는 이점

우리는 어떤 상황에서도 문제 해결을 향해 한 걸음씩 내딛어야 하며 타당한 근거를 바탕으로 일을 매듭 지을 수 있어야 한다. 이 때, 원칙적인 접근이 나침반의 역할을 한다. 그동안 쌓아온 경험을 통해서 감으로 때려 잡는 것이 아니라 원칙적으로 문제에 접근하려 노력해보길 바란다. 비교적 안정적이고 차분한 마음으로 문제를 풀어나갈 수 있게 될 것이다. 원칙이라고 하니 거창하게 느껴지지만, 원칙을 세우는 일은 상황에 따른 대응책을 마련해두는 것과 같다. 자신의 경험을 담아 효율적인 업무 매뉴얼을 작성하고 지속적으로 수정하길 바란다.

트러블슈팅 원칙 예시

고객사의 리눅스 서버에서 운영 중인 웹 애플리케이션에서 발생한 문제를 해결해야 하는 상황이라고 가정한다. 업무 프로세스는 앞에서 말한 것과 같다. 팀 내에 테스트가 가능한 개발 서버가 구축되어 있으며, 해당 고객사에 기술 지원을 담당하는 동료(비개발자)가 있는 상황이다.

1. 시스템의 상호 작용을 이해하면서 영향 범위를 파악한다.
   • 애플리케이션이 어떻게 동작하는지 파악하는 것이 분석의 시작이다.
   • 원인 파악을 위해 필요한 내용을 추려서 고객사에 요청한다.
     (로그, 운영 환경, 설정 파일 등)
   • 최신 패치 버전에서 추가된 결함인지 확인한다. 수정 및 추가된 코드가 원인이라면 그 부분을 집중 분석한다.
2. 고객사로부터 전달 받은 자료를 분석한다.
   • 재요청 해야 할 자료는 없는지 받자 마자 확인해보는 게 좋다.
     (전달 받은 자료가 문제 해결에 별 도움이 안 될 때도 있다.)
   • 이슈에 대해 좀 더 자세한 정보가 필요하다면 고객사의 담당자에게 인터뷰를 요청하는 방법도 있다.
3. 쉽게 재현 가능한 이슈인지 확인한다.
   • 문제의 상황을 똑같이 재현할 방법을 찾으면 정확하게 문제를 해결할 수 있다.
   • 정상 동작을 확인하는 테스트 코드를 먼저 작성하여 문제가 발생하는 상황을 만들어 놓은 뒤에, 테스트를 통과할 수 있도록 개선하여 해결한다.
   • 고객사 에서는 재현이 쉽지만 개발 환경에서 재현이 너무 어렵다면 고객사의 PC에 원격 제어를 요청한다. 그리고 그곳에서 문제 해결의 단서를 모아야 한다. 요청하기 전에 원인을 파악하기 위해 살펴봐야 할 것들에 대해 미리 정리하는 것이 중요하다. 그래야 시간을 효율적으로 쓸 수 있고 새로운 환경에서 당황하지 않을 수 있다.
4. 만약 구현 당시 로그를 남기지 않았다면, 진입점부터 끝까지 코드를 일일이 분석한다.
   (원인 파악을 위한 로깅, 예외 핸들링 코드를 추가하여 고객에게 로그 수집을 부탁하는 방법도 있다.)
5. 어떤 조건에서 문제가 재현 되는지 도저히 파악하기 힘들다면, 코드 및 환경 설정을 면밀하게 분석하여 원인이 될 만한 부분을 찿아 개선한 뒤 경과를 지켜본다.

현상을 직접 재현하거나 로그 분석, 운영 환경 및 데이터 확인으로 원인을 파악하는 경우가 대부분이다. 이런 식으로 상황에 따라 나아갈 방향을 정해두면 일이 단순해지는 효과가 있다. 방향을 잡기 위해 복잡한 머릿속을 정리하는 데 쓰는 에너지와 시간을 확 줄여준다. 원인을 파악하고 문제를 해결하는 데에만 집중할 수 있게 된다.

기록해야 하는 이유

많은 경험을 하는 것도 중요하지만 기록이 더 중요하다. 문제 해결 경험을 토대로 우리의 경험과 원칙을 모두 기록하고 업데이트하자. 이유는 단순하다. 기록하지 않으면 잊어버린다. 다시 떠올리는 데 시간이 든다. 소중한 시간을 들여 무언가 배웠다면 모두 기록해두어라. 기록은 흐르는 시간을 붙잡아 두는 유일한 방법이다. 시간이 조금만 지나도 과거의 기억 중 대부분의 것들을 머릿속에서 빠르게 꺼낼 수 없게 된다. 무엇이든 기록하는 습관을 들이고 필요할 때마다 찾아봐야 한다. 그 과정이 반복되다 보면 스스로 성장하고 있음을 실감하게 될 것이다.

가장 큰 장점은 정리된 머릿속을 한 눈에 볼 수 있게 된다는 점이다. 그러면 복잡한 문제를 해결해야 할 때 불필요한 곳에 에너지를 쓰지 않고 필요한 곳에만 집중할 수 있어 효율적인 일 처리가 가능하다. 필자는 원인 파악의 과정 또한 기록하면서 머릿속을 눈으로 훤히 볼 수 있게 만들기 위해 노력하는데, 이런 노력이 막막한 상황에서 문제 해결을 향해 한 걸음씩 내딛는데 큰 도움이 된다. 기록하는 것이 도움 된 적은 많지만, 기록하지 않는 것이 도움 된 적은 없었다. 그리고 후임에게 인수인계를 하거나, 상사에게 일의 진척을 보고하는 일도 수월해진다. 하지만 기록하지 않으면 머릿속에 들어있는 것들이 많아도 그게 뭔지 알기 힘들어진다. 정리가 되지 않아서 추상적이고 애매한 생각들로 가득해진다. 그래서 감과 습관에 의존하게 된다.

이 글을 읽으면서 원칙적 접근과 기록의 중요성에 대해 생각해 볼 수 있었기를 바란다. 무엇이든 직접 경험해보고 느껴봐야 필요성을 느낄 수 있다. 여러분들께 미션을 하나 주겠다. 구글에 한 번 검색해서 찾은 내용은 다시는 검색하지 않는다는 목표를 세우고 사소한 것부터 기록하는 습관을 만들어보자. 해보고 별로면 안 하면 된다. 손해 볼 것이 하나도 없으니 도전해보라!