데이터 카탈로그

데이터 카탈로그는 수집된 이벤트와 속성을 팀이 같은 의미로 읽도록 정리하는 화면입니다. 분석을 시작하기 전에 전환 이벤트와 상태를 먼저 정해 두세요. 퍼널·획득·알림·세그먼트가 모두 이 설정을 따릅니다.

진입 경로Copy Anchor Link

• /dashboard/[orgId]/[projectId]/events: 사이드바의 데이터 카탈로그, 단축키 G E. 상단에서 이벤트 / 속성 탭을 고릅니다(?tab=properties).
• 헤더의 이벤트 원본은 이벤트 스트림으로, 트래픽 품질은 /dashboard/[orgId]/[projectId]/events/traffic으로 이동합니다.

링크로 화면 상태 공유하기Copy Anchor Link

지금 보고 있는 화면 상태는 모두 URL에 들어갑니다. 주소를 복사해 보내면 받는 사람도 같은 화면을 봅니다.

?panel=은 두 가지로 쓰입니다. 인스펙터가 열려 있으면 그 안의 탭을 가리킵니다(overview·properties·settings·history·code, 속성 인스펙터는 overview·settings). 인스펙터가 닫혀 있으면 목록 옆 패널을 가리킵니다(template·import·categories·triage). 패널을 열면 열려 있던 인스펙터는 닫힙니다.

?days=는 이벤트 탭의 볼륨 열과 추이선에 적용하는 기간입니다(목록 위 7일·30일·90일). 상태 판정은 이 값을 따르지 않고 항상 30일 기준입니다. 7일로 판정하면 관측 기간이 짧아서 트래픽이 있는 이벤트가 모두 "신규"로 보이기 때문입니다.

검색창으로 필터 걸기Copy Anchor Link

필터 버튼(상태·카테고리·태그·전환)과 검색창은 서로 연결돼 있습니다. 버튼으로 고른 필터는 검색창에 나타나고, 검색창에 입력한 필터는 버튼에 반영됩니다.

결제 is:conversion status:deprecated category:checkout tag:pay

속성 탭에서는 type:number scope:profile is:hidden을 씁니다.

한 필드에 값을 여러 개 줄 때는 괄호로 묶습니다. 괄호 안의 값 가운데 하나만 맞아도 걸립니다.

status:(new or never_seen)

절끼리는 AND, 괄호 안은 OR입니다. 앞에 -를 붙이면 제외입니다(-category:internal). status:new or status:never_seen처럼 풀어 쓰면 안 됩니다. or는 괄호 안에서만 통하고, 풀어 쓴 두 절은 AND로 묶여 어떤 이벤트도 걸리지 않습니다.

이벤트 상태 7종Copy Anchor Link

상태는 점과 단어로 함께 표시됩니다. 색만으로 구분하지 않습니다.

미발생과 비활성은 다릅니다. 미발생은 카탈로그에는 있지만 최근 30일 동안 한 번도 오지 않은 이벤트이고, 비활성은 오다가 끊긴 이벤트입니다. 둘을 구분하지 않으면 실제로는 없는 장애를 찾게 됩니다.

판정은 최근 30일 관측만 봅니다. 그래서 카탈로그에 등록돼 있지만 30일 넘게 오지 않은 이벤트는 비활성이 아니라 미발생으로 보입니다. 최근 30일 가운데 최근 7일에만 관측된 이벤트는 예전에 오던 이벤트라도 신규로 보입니다. 직접 지정한 상태(지원 중단·보관·내부)는 관측보다 우선합니다.

보관한 이벤트는 이벤트 목록에 나오지 않습니다. status:archived로 걸러도 마찬가지입니다. 상태 필터의 보관 숫자로 개수만 확인할 수 있습니다. 되돌리려면 ?event=<이름>&panel=settings 주소로 인스펙터를 열어 상태를 바꾸세요. 내보내기 파일에는 보관한 이벤트도 들어 있습니다.

정리 패널Copy Anchor Link

목록 위 정리 필요 카드는 신규와 미발생 이벤트를 셉니다. 카드를 누르면 status:(new or never_seen) 필터가 걸립니다. 필터가 비어 있을 때 뜨는 정리할 이벤트 N개 안내에서 모아 보기는 같은 필터를 걸고, 한 번에 정리는 정리 패널(?panel=triage)을 엽니다. 정리 패널에서는 인스펙터를 이벤트마다 열지 않고 여러 이벤트를 한 번에 정리합니다.

패널에서 하는 일은 두 가지입니다.

• 행마다 다른 값: 표시 이름과 카테고리를 행에 직접 입력하고, 그 행들을 선택한 뒤 카탈로그에 저장으로 한 번에 저장합니다.
• 여러 행에 같은 값: 고른 행 전체에 카테고리 지정·보관·내부 이벤트로를 적용합니다.

일부가 실패하면 실패한 행만 선택된 채로 남습니다. 같은 버튼을 다시 누르면 그 행만 재시도합니다.

정리 대상은 상태로 정해집니다. 이름과 카테고리를 붙여도 신규·미발생 상태는 그대로라서 목록과 정리 필요 숫자에 계속 남습니다. 미발생은 이벤트가 들어오기 시작하면 신규로 바뀌고, 신규는 첫 관측 후 7일이 지나야 빠집니다. 보관하거나 내부로 옮긴 이벤트는 바로 빠집니다.

카테고리는 목록에서 고르지 않고 직접 입력합니다. 이미 쓰는 이름은 자동완성으로 제안하고, 새 카테고리도 여기서 입력해 만듭니다.

이 패널의 판정 기간은 화면의 ?days=와 상관없이 30일로 고정입니다. 이유는 위와 같습니다. 7일로 판정하면 트래픽이 있는 이벤트가 모두 정리 대상이 됩니다. 패널은 볼륨이 큰 순서로 최대 500개 이벤트 안에서 대상을 찾습니다.

이벤트 인스펙터Copy Anchor Link

행을 클릭하면 목록 오른쪽에 인스펙터가 열립니다. 목록은 그대로 보입니다.

• 개요: 표시 이름·설명·아이콘·색상·태그. 저장을 눌러야 반영되고, 되돌리기는 저장 전 수정을 버립니다.
• 속성: 이 이벤트에 담겨 오는 속성과 고유 값 수, 빈 값 비율. 행을 누르면 설명·타입·숨김을 고치고 상위 값 10개를 봅니다. 옆의 사용 현황은 이 이벤트를 쓰는 리포트와 알림을 보여 줍니다.
• 설정: 전환 여부와 상태(활성·지원 중단·보관·내부). 누르는 즉시 저장됩니다.
• 이력: 필드 단위 변경 기록.
• 코드: 이 이벤트를 보내는 코드. JavaScript·TypeScript·React·Node 가운데 골라 복사합니다.

목록에서 바로 하는 일도 있습니다. 전환 열의 스위치로 전환 여부를 바꾸고, 행 끝의 코드·이력으로 그 탭을 바로 엽니다. $exception 행에는 에러 트래킹에서 보기가 더 있습니다.

관리하는 메타데이터Copy Anchor Link

rollupProperties는 인스펙터에 편집 칸이 없습니다. 카탈로그 파일로 관리하거나, 메트릭 관리 탐색 탭의 롤업에 추가 버튼으로 추가합니다. 바꾸면 전체 이력 재계산이 예약됩니다.

상태를 내부로 바꾸면 그 이벤트는 이벤트 수 집계에서 빠지고(대시보드의 이벤트 추이 타일, 메트릭 관리의 이벤트 조회), 분석 화면의 이벤트 선택기에도 기본으로 나오지 않습니다. 퍼널·리텐션처럼 정의에 이벤트 이름이 이미 들어 있는 분석은 상태와 상관없이 그대로 계산합니다.

표시 이름은 이벤트 스트림 검색창에서도 쓸 수 있습니다. 스트림은 원본 키(purchase_completed)를 저장하지만, name:"결제 완료"처럼 화면에서 본 이름으로 검색하면 그 이름을 쓰는 원본 키까지 넓혀 찾습니다. 검색창에는 입력한 글자가 그대로 남으므로, 링크를 공유해도 같은 검색어가 전달됩니다. 한 표시 이름을 두 이벤트가 쓰고 있으면 둘 다 나옵니다.

속성 탭Copy Anchor Link

속성 탭에는 프로젝트에서 관측된 속성 키가 모두 모여 있습니다. 이벤트를 하나씩 펼치지 않아도 됩니다. 열은 속성·타입·스코프·관측 이벤트·마지막 발생·숨김이고, 행을 누르면 속성 인스펙터(개요·설정)가 열립니다.

• 타입: 수집할 때 처음 관측한 값에서 기록한 타입이거나 사람이 고친 타입입니다. 한 번 정해지면 수집이 다시 덮어쓰지 않습니다. 정해진 것이 없으면 미정으로 보입니다. 이벤트 인스펙터의 속성 탭은 저장된 타입이 없을 때 표본에서 추정한 값을 (추정)으로 흐리게 보여 줍니다.
• 타입을 바꾸면 필터 연산자와 쿼리 캐스팅이 바뀝니다. 이미 저장된 필터가 새 타입에서 허용되지 않는 연산자를 쓰고 있을 수 있습니다. 설정 안 됨으로 되돌리면 표본에서 추론한 값을 다시 씁니다.
• 숨김: 선택기·브레이크다운 차원·롤업 후보·필터 제안에서 빠집니다. 필터로는 계속 쓸 수 있습니다. 숨긴 속성은 목록에서도 빠지므로, 다시 보려면 숨긴 속성 포함을 켜세요.
• 스코프(event / profile)가 다르면 이름이 같아도 다른 속성입니다. 이벤트의 plan과 프로필의 plan은 서로 다릅니다. 목록 위 전체·이벤트·프로필로 좁힙니다.
• 속성 탭의 검색과 필터는 지금 보이는 페이지(25개) 안에서만 걸러집니다. 찾는 속성이 안 보이면 스코프를 좁히거나 페이지를 넘겨 보세요.

파일로 주고받기Copy Anchor Link

목록 위 가져오기·내보내기, 템플릿 적용, 카테고리 제안 버튼이 각각 패널을 엽니다.

• 내보내기: reopt-data.events.json으로 받습니다. CLI가 찾는 파일 이름이라 저장소에 두면 reopt-data event push가 바로 읽습니다. 보관한 이벤트와 롤업 속성도 들어 있습니다.
• 가져오기: 없는 것만 추가 또는 전부 덮어쓰기를 고릅니다. 한 번에 이벤트 500개까지입니다. 덮어쓰기는 콘솔에서 쓴 값도 파일 내용으로 바꾸므로 확인을 한 번 더 받습니다. 파일의 이벤트에서 생략한 필드는 그대로 두지 않고 기본값으로 처리합니다. rollupProperties를 적지 않은 이벤트는 덮어쓸 때 롤업 속성이 비워집니다.
• 템플릿 적용: 템플릿의 이벤트 가운데 카탈로그에 아직 없는 것만 추가합니다. 이미 있는 이벤트의 표시 이름이나 설명은 바꾸지 않습니다.
• 카테고리 제안: checkout_처럼 이벤트 이름의 공통 접두사에서 카테고리를 제안합니다. 적용을 누르면 그 묶음에 카테고리가 지정됩니다.

콘솔의 가져오기는 파일에 적힌 이벤트만 반영합니다. 파일에 없는 이벤트를 보관으로 넘기는 것은 CLI의 reopt-data event push입니다.

속성을 파일로 관리하기Copy Anchor Link

파일 version: 2에는 properties 절이 있습니다. 여기에는 사람이 정한 타입·설명·숨김 세 가지만 담깁니다.

{
  "version": 2,
  "projectId": "prj_123",
  "events": { "purchase": { "conversion": true } },
  "properties": {
    "event": { "plan": { "propertyType": "string", "description": "요금제 코드" } },
    "profile": { "signup_source": { "hidden": true } },
  },
}

이벤트와 다른 규칙이 하나 있습니다. reopt-data event push는 파일에서 빠진 이벤트를 보관으로 넘기지만, 파일에 없는 속성은 관측된 그대로 남습니다. 속성은 수집될 때 생기므로, 파일에서 빼도 다음 이벤트가 들어오면 다시 생기기 때문입니다.

파일에 선언한 속성에는 이벤트와 같은 규칙이 적용됩니다. {}는 "설명 없음, 숨김 아님"으로 처리하므로, 콘솔에서 쓴 설명을 파일에 적지 않으면 지워집니다.

내보내기는 사람이 손댄 속성(설명이 있거나 숨김)만 파일에 씁니다. 관측만 된 키까지 쓰면 파일이 트래픽에 따라 달라져 배포마다 어긋납니다. 손댄 속성이 하나도 없는 프로젝트는 version: 1 파일을 그대로 받습니다. 빈 properties 절은 "속성을 선언하지 않는다"는 뜻이 되므로 넣지 않습니다.

CI에서 미선언 속성 검사하기Copy Anchor Link

reopt-data event verify는 기본 설정에서 미선언 속성을 보고하지 않습니다. 더 엄격하게 검사하려면 아래 두 플래그 가운데 골라 켭니다. 두 플래그는 서로를 포함하지 않고, 보고 대상이 겹치지 않습니다.

--strict-observed는 SDK가 자동으로 보내는 키($로 시작하는 예약 키, $pageview의 path 같은 자동 이벤트 속성)를 제외합니다. 앱이 정한 키가 아니기 때문입니다. 다만 이름이 같아도 앱이 보낸 purchase에 담긴 value는 앱의 키이므로 잡힙니다.

주의: 속성을 추가한 PR에서는 잡히지 않습니다. 그 시점에는 서버가 그 키를 아직 본 적이 없기 때문입니다. 배포 후 첫 이벤트가 들어와야 행이 생기므로, 검사는 그다음 PR에서 실패합니다. 이 점을 감수할 저장소에서만 켜세요. 명령과 종료 코드는 CLI에 있습니다.

트래픽 품질Copy Anchor Link

/events/traffic은 수집된 트래픽 가운데 사람으로 판정된 비중을 보는 화면입니다. 기간은 최근 30일로 고정이고 필터는 없습니다.

아래 격리 사유 표는 판정 이유별 이벤트 수입니다. 이유가 여러 개인 이벤트는 이유마다 한 번씩 세므로, 표의 합이 격리된 이벤트 수보다 클 수 있습니다. 격리된 이벤트는 따로 보관되어 이벤트 스트림과 이 카탈로그의 볼륨에 들어가지 않습니다.

주의할 점Copy Anchor Link

• 여러 이벤트를 한 번에 바꾸는 곳은 정리 패널입니다.
• 상태 필터의 숫자와 이벤트·전환 이벤트·정리 필요 카드는 필터를 걸기 전의 프로젝트 전체 개수입니다. 지금 화면에 보이는 개수가 아닙니다.
• 이벤트 목록은 볼륨이 큰 순서로 한 페이지에 25개씩 나옵니다.
• 목록이 비어 있을 때와 불러오지 못했을 때는 다르게 표시됩니다. 불러오지 못했을 때는 다시 시도 버튼이 있습니다.

다음 단계Copy Anchor Link

• 이벤트 스트림: 원본 이벤트 하나하나 보기
• 메트릭 관리: 롤업 속성과 제외가 집계에 반영된 결과 보기
• 퍼널 분석: 전환 이벤트로 단계 만들기
• CLI: 카탈로그 파일을 저장소에서 push·verify 하기