이벤트 스키마 디자인
이벤트 스키마는 데이터를 내보내는 코드와 이를 사용하는 모든 쿼리, 대시보드, 알림 또는 내보내기 간의 계약입니다. 계측 전 소량의 설계로 수개월 동안의 모호한 데이터를 방지할 수 있습니다.
결과 이름 지정
api_request_completed, job_failed 또는 subscription_renewed와 같은 안정 명사와 과거 시제 결과를 사용하세요. 자주 변경되는 UI 문구는 피하세요. 성공과 실패가 동일한 유용한 필드를 공유하는 경우 제어된 status 값이 있는 하나의 이벤트가 별도의 테이블보다 비교하기 쉬운 경우가 많습니다.
질문에서 필드 선택
계획된 각 질문에 대해 작업을 식별합니다.
- 필터에는 환경, 기능, 경로 또는 상태와 같은 필드가 필요합니다.
- 그룹에는 모델, 릴리스 또는 오류 유형과 같은 제어된 차원이 필요합니다.
- 계산에는 명시적인 단위를 사용하여 입력된 측정값이 필요합니다.
- 조사에는 관련 사건을 연결하는 안전한 식별자가 필요합니다.
latency가 아니라 latency_ms를 기록하세요. 숫자 값을 숫자로 저장하고 부울을 부울로 저장합니다. UTC 타임스탬프를 사용하세요. 원시 URL보다는 route_template를 선호하고, 무한한 예외 메시지보다는 error_type를 선호하세요.
식별자가 사람, 계정, 요청 또는 직무를 나타내는지 여부를 문서화합니다. 필드에 민감한 데이터가 포함될 수 있는 경우 이벤트가 생성되기 전에 해당 데이터를 생략하거나 변환하세요.
변화 계획
일반적으로 추가 변경이 가장 안전합니다. 쿼리는 새로운 null 허용 필드를 허용할 수 있습니다. 필드 이름을 바꾸거나 해당 유형을 변경하면 모든 소비자가 중단될 수 있습니다. 의미 체계가 크게 변경되면 event_version를 추가하고 마이그레이션 창을 처리하는 쿼리를 작성하고 소비자가 이동한 후에만 이전 모양을 제거합니다.
검증을 위해 대표적인 성공, 실패, 재시도 및 시간 초과 샘플을 유지하세요. 계측 변경 사항을 출시하기 전에 중요한 SQL을 실행하세요. 스키마는 실제 분기에서 생성된 값이 문서화된 의미와 일치할 때만 완성됩니다.
체크리스트 검토
이벤트에 명확한 소유자, 제한된 상태 값 집합, 명시적 단위, 안전한 식별자 및 보존 필요성이 있는지 물어보세요. 하나 이상의 실제 쿼리가 각 필드를 사용하는지 확인하세요. 단지 사용 가능하다는 이유로 포함된 값을 제거하세요.
전체 이벤트 계약 예시는 스키마 진화, 민감한 데이터 수정 및 SQL 레시피를 참조하세요.