다음 사람에게 남기는 것

계약 기간이 끝나가는 미디어 시스템이 있었다. ActiveMQ와 Hadoop HDFS, ffmpeg 워커가 물려 있는 구성이었고 넘길 문서를 쓰기 시작하고 보니 무엇부터 적을지가 정해지지 않았다.

Open Table of contents

목표와 제약

받는 사람이 나 없이 ffmpeg 변환 실패나 HDFS 용량 장애를 처리할 수 있는 상태가 목표였다. 전부 적는 것이 아니라 그 상태를 만드는 데 필요한 것만 골라 적는 것이 범위였다.

남은 시간이 2주뿐이었고 그 사이에도 ffmpeg 변환 실패 대응 같은 평소 운영 업무가 그대로 있었다. 다 못 채운다는 전제로 순서를 정해야 했다.

처음에는 하나의 문서에 전부 적으려고 했는데, 쓰다 보니 성격이 전혀 다른 것들이 섞여 들어갔다.

접속 정보처럼 바뀌면 문서가 바로 틀려지는 것이 있고, 설계 의도처럼 오래가는 것이 있었다. 한 문서에 두면 자주 바뀌는 것 때문에 전체가 낡은 것으로 보인다.

자리를 셋으로 갈랐다. 접속·계정 값은 .env.example과 별도 파일에, 설계 의도와 판단 근거는 Markdown 문서에, 반복 작업은 Bash 스크립트에 두었다.

Bash 스크립트로 옮긴 절차는 문서에 다시 적지 않았다. 적어 두면 스크립트와 문서 둘이 조용히 갈라진다.

값은 바뀌면 그 파일만 고치면 되고 문서는 그대로 유효하다. 수명이 다른 것을 같은 자리에 두지 않는 것이 이 구분의 이유였다.

장애 대응만 적다 보니 정상일 때가 어떤 모양인지는 통째로 빠져 있었다. ffmpeg 워커가 평소 몇 개 도는지도 없었다. 큐 길이가 200이면 정상인지 이상인지 받는 사람은 모른다.

Grafana 대시보드에 뜨는 주요 지표의 평소 범위를 함께 적었다. ActiveMQ 큐 길이는 평소 50~200, HDFS 여유는 30% 이상 같은 식이다.

시간이 모자랄 것을 알고 순서를 정했다. 먼저 장애 시 필요한 것, 다음 정기 작업, 마지막이 설계 배경이었다.

ActiveMQ 큐 구성을 왜 그렇게 나눴는지 같은 설계 배경은 절반쯤 적은 상태로 기간이 끝났다. 대신 못 적은 항목을 목록으로 남기고 어디를 보면 알 수 있는지를 함께 적었다.

빈칸을 감추지 않고 빈칸으로 표시한 것이 이 문서에서 중요했다. 없는 것을 없다고 적어야 받는 쪽이 그것부터 채운다.

넘기고 나서 두 번 질문을 받았는데 둘 다 못 적은 항목 목록에 들어 있던 것이었다.

답을 주면서 그 내용을 문서에 넣으라고 하지 않았다. 이제 그 문서는 받는 쪽의 것이고 고치는 것도 그쪽 몫이다.