수집과 API
데이터가 처리되는 방식
수집한 이벤트가 저장되고 분석 화면에 나타나기까지의 흐름, 갱신 주기, 프로젝트 사이의 격리를 설명합니다.
SDK가 보낸 이벤트가 어떤 단계를 거쳐 화면에 나타나는지 설명합니다. 방금 보낸 이벤트가 아직 보이지 않거나 화면마다 숫자가 조금 다를 때 보세요.
수집에서 화면까지
- 수집: SDK가
POST /api/track으로 이벤트를 보냅니다. 자격증명 확인, 형식 검증, 중복 제거, 데이터 포인트 확인이 이 요청 안에서 끝납니다. - 원본 저장: 통과한 이벤트는 원본 그대로 먼저 저장되고, 응답은 이 시점에 돌아갑니다.
- 분석 반영: 그 뒤에 세션과 프로필을 정리하고 분석 데이터에 기록합니다. 예외 이벤트는 에러 이슈로 묶이고, AI 이벤트는 AI 관측 기록이 됩니다. 이벤트에 담긴 속성 키는 데이터 카탈로그에 나타납니다.
- 화면: 이벤트 스트림과 실시간 화면에 먼저 보이고, 집계가 필요한 화면은 아래 갱신 주기에 따라 반영됩니다.
분석 반영이 실패하면 자동으로 다시 시도합니다. 원본 이벤트는 그대로 남아 있으므로, 자동 재시도로 반영되지 않은 이벤트도 나중에 다시 반영할 수 있습니다.
수집 응답을 받은 이벤트가 오래 보이지 않으면 응답의 requestId와 함께 문의 창구로 알려 주세요.
이미 저장된 이벤트는 같은 eventId로 다시 보내도 중복으로 집계되고 두 번 저장되지 않습니다.
화면별 갱신 주기
| 대상 | 반영되는 시점 |
|---|---|
| 이벤트 스트림 | 분석 반영 직후. 방금 보낸 이벤트는 여기서 먼저 확인합니다 |
| 실시간 | 연결해 둔 동안 들어오는 이벤트를 바로 보여줍니다 |
| 시간별 롤업 | 약 5분마다 갱신합니다. 가장 최근 시간대는 원본 이벤트에서 읽어 합치므로 최신 숫자도 빠지지 않습니다 |
| 대시보드 타일 | 결과를 5분 동안 캐시합니다 |
| 동적 세그먼트 | 저장하면 바로 계산을 시도하고, 그 뒤로는 주기적으로 다시 계산합니다 |
| 알림 | 5분마다 평가하고, 끝난 시간 구간만 봅니다 |
| 분석 조회 API | /api/v1/query/*의 계산 결과를 5분 동안 캐시합니다 |
화면마다 숫자가 조금 다르게 보이는 것은 대개 이 주기 차이 때문입니다. 롤업에서 온 숫자인지 원본에서 읽은 숫자인지는 메트릭 관리에서 확인하세요.
집계에 들어가지 않는 것
- 봇과 의심 트래픽: 브라우저 수집에서 사람이 아닌 트래픽으로 판정된 이벤트는 세션·프로필·분석 화면에 반영하지 않고 데이터 포인트도 차감하지 않습니다. 건수와 사유는 데이터 카탈로그의 트래픽 품질에서 확인합니다.
- 내부로 표시한 이벤트: 데이터 카탈로그에서 상태를
내부로 둔 이벤트는 이벤트 수 집계에서 빠집니다. - 중복 이벤트: 이미 받은
eventId와, 브라우저에서 5초 안에 똑같이 반복된 이벤트는 저장하지 않습니다.
프로젝트 사이의 격리
- 데이터는 프로젝트 단위로 나뉩니다. write key와 서버 자격증명은 프로젝트 하나에 묶여 있고, 그 프로젝트에만 쓰고 읽을 수 있습니다.
- 분석 조회 API에 다른 프로젝트 id를 보내면
403으로 거절됩니다. - 쿼리 화면에서 직접 쓴 SQL은 지금 보고 있는 프로젝트의
events,sessions,profiles만 읽습니다. 다른 프로젝트의 행은 보이지 않습니다. - 콘솔 접근은 조직 멤버십을 따릅니다. 조직의 멤버만 그 조직의 프로젝트를 열 수 있습니다. 공개 데모 워크스페이스만 예외로, 로그인한 누구나 읽을 수 있습니다.
시간대
프로젝트 화면의 날짜와 조회 기간은 프로젝트 시간대를 기준으로 표시합니다. 사용량 월과 알림의 평가 구간처럼 UTC를 기준으로 하는 항목은 해당 문서에 따로 적혀 있습니다.
보존과 삭제
- 프로젝트의 보존 기간은 원본 이벤트와 분석 데이터에 함께 적용됩니다. 기간을 정해 두고 관리자가 프로젝트 설정에서 정리를 실행하면 그 이전 데이터가 지워집니다.
- AI 호출 기록과 세션 리플레이 녹화는 각자의 보존 기간에 따라 자동으로 정리됩니다.
- 지운 데이터는 되돌릴 수 없습니다. 자세한 내용은 비용과 보존 정책을 보세요.
다음 단계
- 수집 요청의 형식과 오류 코드는 데이터 수집과 거버넌스
- 자격증명과 조회 API는 HTTP API
- 화면 전체 지도는 서비스 맵