기록해 뒀는데 왜 또 걸렸나

몇 년치 작업 기록을 훑다가 같은 함정이 몇 번씩 나오는 것을 세어 봤다.

매번 원인과 해결책까지 적어 뒀는데 매번 다시 걸렸다.

Table of contents

원인 — 검색되지 않는 자리의 기록

시각 기준 혼합을 예로 들면 이렇다. information_schema.innodb_trx 의 trx_started 는 UTC 로 오는데 MySQL 8.0 참조 매뉴얼의 날짜·시간 함수 항목대로 NOW() 는 세션 시간대의 값을 돌려주므로 세션이 KST 면 둘을 그냥 빼면 9시간이 허위로 더해진다. 그래서 9시간짜리 장기 잠금으로 보이지만 실제 대기는 1분 남짓이고, 같은 문서의 UTC_TIMESTAMP() 로 빼야 맞는다.

이걸 대여섯 번 겪었고 그때마다 원인을 적었다. 문제는 다음에 같은 상황을 만났을 때 무엇으로 검색할지 모른다는 것이다. 손에 쥔 증상은 잠금이 9시간이라는 것이고 기록의 제목은 시간대 처리인데 이 둘이 안 이어진다. 기록은 원인을 기준으로 정리되고 다시 만날 때 손에 있는 것은 증상뿐이다.

조치 — 코드를 쓰는 자리와의 거리

접두어 이중 적용은 예닐곱 번 겪었다. Laravel 이 테이블 이름에 prefix 를 자동으로 붙이는데 DB::raw() 안에서는 안 붙이므로 같은 파일 안에서 규칙이 정반대가 된다.

예닐곱 번 다 다른 사람이 다른 파일에서 겪었다. 기록에는 있었지만 그 코드를 쓰는 자리에는 없었다. 줄이려면 기록보다 앞에 무언가가 있어야 한다. 그 함수를 감싸는 헬퍼로 규칙을 한 곳에 가두거나 DB::raw() 에 접두어가 없으면 잡는 검사를 붙이거나 최소한 그 파일 상단에 세 줄짜리 주석을 단다. 앞의 둘은 두 가지 방법이 있었던 셈인데 헬퍼로 가두는 것과 검사로 잡는 것이다. 앞쪽을 골랐다. 이유는 검사는 잘못 쓴 뒤에 잡고 헬퍼는 잘못 쓸 자리를 없애서다. 대신 기존의 DB::raw() 를 전부 헬퍼로 옮기는 것을 감수했다. 근거는 남겨 둔 DB::raw() 하나가 다음 사람의 본보기가 된다는 점이다. 셋 다 기록보다 강한 것은 코드를 쓰는 사람 눈에 들어오는 자리에 있다는 점 때문이다.

재발 횟수가 가리키는 것

십여 번 반복된 것은 사람이 게을러서가 아니라 그 작업 흐름에 그 함정이 상시로 놓여 있다는 뜻이다. 파일명 정규화 문제는 macOS 와 Linux 사이에서 파일을 옮길 때마다 나므로 옮기는 일이 잦으면 매번 난다.

그러니 기록할 것이 아니라 옮기는 절차 자체에 변환을 넣어야 했고 실제로는 rsync 에 --iconv 옵션 하나를 붙이면 되는 일이었다. 몇 번씩 반복된 항목은 조심하자는 신호가 아니라 자동화하자는 신호다.

판단 기준 — 횟수별 대응

기록을 쌓기만 했을 때는 항목들이 다 비슷해 보였는데 세어 보니 갈렸다. 한 번 난 것은 그때 상황이 특이했던 것일 수 있지만 다섯 번 난 것은 구조다.

그래서 횟수에 따라 대응을 나눴다. 한 번이면 기록만 남기고, 두세 번이면 그 코드가 있는 자리에 주석이나 검사를 붙이고, 네 번 이상이면 절차에서 아예 뺀다. 도구 옵션이나 헬퍼나 자동 검사로 옮기는 것이다.

증상으로 찾을 수 있는 기록

원인 중심으로 쓴 기록은 원인을 알고 나서만 찾을 수 있으므로 순서가 뒤집혀 있다. 지금은 제목이나 첫 줄에 증상을 그대로 넣는다.

잠금 대기가 9시간으로 나온다거나 테이블이 없다는데 prefix 가 두 번 붙었다거나 한글 주석이 있는데 중괄호 오류가 난다는 식이다. 다음에 그 상황을 만난 사람이 손에 쥐고 있는 문장이 정확히 그것이다.

정리

• 기록은 원인 순으로 쌓이고 다시 만날 때 손에 있는 것은 증상이다
• 그래서 필요한 순간에 검색되지 않는다
• 기록보다 코드를 쓰는 자리에 있는 것이 강하다
• 헬퍼와 검사와 그 파일의 주석이 그런 자리다
• 반복 횟수가 원인의 지표다
• 여러 번 났으면 개인 부주의가 아니라 구조다
• 네 번 이상이면 절차에서 뺀다
• 기록 제목에 증상을 그대로 넣는다