에이전트가 오류 메시지를 리팩토링하고 디버깅 흔적을 조용히 삭제한 경험

리팩토링은 성공적으로 완료되었다. CI는 통과했고, diff도 깔끔해 보였다. 일주일 후, 프로덕션 환경에서 500 에러가 발생했고 로그에는 정확하게 다음과 같이 기록되어 있었다: Internal error.

예전에는 이 줄이 이렇게 읽혔었다: invoice 4412 could not be voided: ledger row locked by migration job.

지금은 아무것도 읽히지 않는다. 에이전트가 일반화하여 삭제해 버린 것이다.

실제로 무슨 일이 일어났나

원래에는 메시지가 다른 두 개의 catch 블록이 있었다. 에이전트는 이것을 중복으로 보고 하나의 logAndRethrow(err) 헬퍼 함수로 통합했다. 이 헬퍼는 하나의 인자, 즉 err만 받는다. 인보이스 ID, 잠금 보유자, 호출하는 작업 등 모든 것이 사라졌는데, 이는 그 어떤 것도 '정상 경로(happy path)'에 포함되지 않았기 때문이다.

이것은 정확했다. 깔끔했고. 하지만 또한 전체 diff에서 가장 비용이 많이 드는 변경이었으며, 새벽 2시가 되어서야 그 대가를 치르게 되었다.

에이전트들이 이렇게 하는 이유

그들은 DRY(Don't Repeat Yourself) 원칙과 가독성을 최적화한다. invoice 4412 could not be voided 같은 문자열은 하드코딩된 악취처럼 보인다. 이 메시지가 새벽 3시에 실패를 가리키는 유일한 단서라는 사실은 그들이 최적화하는 신호에 포함되지 않는다. 그들은 당신의 온콜 로테이션(on-call rotation) 모델을 가지고 있지 않다.

당신의 테스트도 이를 잡아내지 못한다. 왜냐하면 테스트가 메시지가 아닌 에러 클래스를 기반으로 단언하기 때문이다. 모니터링 시스템 역시 이를 포착하지 못하는데, 여전히 500 에러를 하나로 계산하기 때문이다. 인간은 동일한 문자열의 벽에 부딪히고 열 개의 코드 경로 중 어느 것이 고장 났는지 알아내기 위해 재현해야만 한다.

내가 지금 사용하는 diff 규칙

리팩토링이 throw나 catch를 건드리고, 새로운 메시지가 이전 메시지보다 보간 변수(interpolation variables)가 적다면, 그것은 경고 신호이다. 멈춰 서서 질문해야 한다: 이 컨텍스트는 무엇을 삭제했고, 지금 어디로 갔는가?

오류 메시지를 미래의 자신이 스트레스를 받으며 읽게 될 계약처럼 취급하라. 공용 API를 리팩토링하는 방식대로 리팩토링하라. 즉, 호출자(그리고 로그)가 의존하는 필드를 보존해야 한다. 이들을 enum이나 구조화된 에러 객체로 이동시키는 것은 괜찮지만, 하나의 일반적인 문자열로 평탄화(flattening)하는 것은 아니다.

이것은 오류가 경계를 넘나들 때 더 날카로워집니다. API 응답의 오류 형태는 명세(spec)의 일부입니다. 생성된 클라이언트가 이를 파싱하고, 그룹별로 모니터링하며, SDK 사용자는 이를 기반으로 분기합니다. 에이전트가 오류 열거형(error enum)을 '단순화'하거나 필드를 삭제할 때, 모든 다운스트림 시스템은 똑같은 방식으로 조용히 깨집니다. 저는 이 계약(contract)을 Powerduck에 로컬로 보관하고 에이전트 변경 후 라이브 엔드포인트에 대해 재실행합니다. 오류 응답의 드리프트는 성공 응답의 드리프트와 똑같은 방식으로 나타나며, 로그에서 발견하는 것보다 CI(지속적 통합)에서 잡는 것이 더 저렴합니다.

대략적인 규칙 (Rough rule)

오류 문자열을 짧게 만든 녹색 리팩토링은 그렇지 않은 경우보다 한 번 더 검토할 가치가 있습니다.

가장 일반적인 오류 메시지를 새벽 2시에 받은 적이 있나요?