흩어진 분석 이벤트, 정의 파일 하나로 잠근 하루

이벤트를 심을 때는 다 기억할 것 같은데, 몇 달 지나면 이 이벤트가 뭘 재는지 아무도 모르게 돼요. 혹시 이런 적 없나요? 혼자 여러 서비스를 운영하면 더 심해져요. 같은 활성화 이벤트인데 앱마다 이름이 조금씩 달라지는 식이에요.

어제 저녁, 5개 프로젝트에 커밋 5건을 쌓으며 이 문제를 정리했어요. 그 기록을 남겨요.

정의 파일 하나가 기준이 되게

시작은 지표 정의를 코드 밖 한곳에 두는 일이었어요. yaml 정의 파일에 이벤트와 지표를 적고, 검증 스크립트와 조회용 CLI를 붙였어요. 파일로는 3개예요.

직접 만들어 보니 핵심은 정의 파일이 아니라 검증 스크립트 쪽이었어요. 사람이 손으로 고치는 파일은 언젠가 어긋나요. 어긋난 순간 바로 잡아주는 장치가 없으면 정의 파일도 결국 안 보는 문서가 돼요.

정의 파일→검증 스크립트→앱별 타입 유니온→런타임 allowlist

앱 쪽은 타입으로 잠그기

정의가 있어도 앱 코드가 아무 문자열이나 보낼 수 있으면 소용없어요. 그래서 각 앱의 analytics 모듈에서 이벤트 이름을 타입 유니온으로 고정했어요.

플랜씨(plan-c)에는 AnalyticsEvent 유니온을 만들고 회귀 테스트를 붙였어요. 플랜티(plan-t)는 한 발 더 가서, 이벤트별 속성 맵을 닫힌 형태로 강제하고 런타임에서 값 allowlist까지 검사하게 했어요. 적용해 봤더니 타입만으로는 부족한 지점이 보였거든요. 속성 이름은 컴파일 단계에서 잡혀도, 속성에 들어가는 값은 런타임에만 알 수 있어요.

이벤트가 누구 것인지도 정해야

플랜비(plan-b)는 농구 동호회 운영 매니저라 경기 기록 이벤트가 많아요. 이번에 경기 스탯 이벤트를 club_id로 동호회에 귀속시키고 PostHog 그룹으로 묶었어요. 파일 5개를 고치는 작업이었는데, 대부분 훅 수정과 테스트였어요. 개인 단위로만 쌓이던 이벤트를 모임 단위로 볼 준비예요.

법령·판례 검색 서비스인 플랜엘(plan-l)에는 분석 결과 화면을 실제로 봤는지 재는 활성화 이벤트를 추가했어요. 월 3건 무료인 서비스라, 검색을 했는지보다 결과를 끝까지 봤는지가 더 중요하다고 판단했어요.

하루를 돌아보며

테스트해 보면 정의에 없는 이벤트 이름은 타입 단계에서 걸리고, 허용 밖 값은 런타임에서 걸려요. 레지스트리 CLI를 돌려 보니 지금 정의된 이벤트 목록을 명령 하나로 확인할 수 있고요. 이벤트 하나를 추가하려면 정의, 타입, 테스트 세 군데를 거치게 됐지만, 그 마찰이 오히려 안전장치라고 생각해요.

이벤트를 심는 날보다 이벤트를 믿어야 하는 날이 늦게 와요. 그날의 나를 위해, 오늘 정의부터 잠가두는 편이에요.