이벤트 저장 구조

개요

전송된 이벤트 로그가 BigQuery에 저장되는 구조, attributes JSON 필드의 세부 구조, 전송 규칙을 위반한 로그가 격리되는 방식을 확인할 수 있습니다.

테이블 구조

전송된 이벤트 로그는 회사별 BigQuery 데이터셋의 t_raw_event_log 테이블에 저장됩니다.

테이블 컬럼 구조

저장 위치

항목	형식
테이블	`t_raw_event_log`
파티셔닝	`dateTime` 기준 일별 파티션

컬럼 정의

컬럼명	자료형	필수 여부	설명	예시
`userId`	STRING	Y	계정 기준 유저 식별자	`100001`
`identifierProvider`	STRING	Y	유저 식별자 발급 시스템. `hive` 고정	`hive`
`deviceId`	STRING	Y	단말 기준 유저 식별자	`100000`
`appId`	STRING	Y	Hive 콘솔 > 프로젝트 설정 > App ID에 등록된 App ID	`"com.com2us.game.ios"`
`appIdGroup`	STRING	Y	Hive 콘솔 > 프로젝트 설정 > 프로젝트에서 발급하는 Project ID. `appId`를 기반으로 변환된 값	`com.com2us.game`
`dateTime`	TIMESTAMP	Y	이벤트 발생 시각. `eventTime`을 UTC로 변환한 값	`2026-07-20T05:01:01Z`
`eventName`	STRING	Y	이벤트를 분류하는 이벤트명	`asset_drop`
`checksum`	STRING	N	파이프라인이 주입하거나 시스템이 생성한 필드(`hiveAttributes` 등)를 모두 제외하고, 고객이 전송한 원본 데이터만으로 생성한 해시값	`HW2FTEB56TEEWER`
`bigqueryRegistTimestamp`	TIMESTAMP	N	이벤트가 BigQuery에 저장된 UTC 시각	`2026-07-20T05:02:01Z`
`attributes`	JSON	N	사용자 정의 속성 및 자동 수집 속성이 저장되는 JSON 필드	아래 참조

테이블 구조 주의사항 & Tips

재전송 등으로 동일 이벤트가 중복 저장될 수 있으니, 조회 시 checksum 기준 중복 제거 쿼리를 함께 사용하는 것을 권장합니다.
```
QUALIFY ROW_NUMBER() OVER (PARTITION BY checksum ORDER BY bigqueryRegistTimestamp DESC) = 1
```
전송 규칙을 위반한 이벤트 로그는 이 테이블이 아닌 rescue 테이블에 저장됩니다. 자세한 내용은 데이터 격리를 참고하세요.

attributes 세부 속성

Note

attributes 컬럼은 JSON 타입이며, hiveAttributes와 eventAttributes 두 영역으로 구분됩니다.

attributes 예시

{
  "hiveAttributes": {
    "_clientIp": "220.70.82.0",
    "_dataSource": "custom_server",
    "_fluentd_appid": "com.com2us.game.ios",
    "_fluentd_sender_ip": "43.101.101.33",
    "_fluentd_hostaname": "9104813d31ab",
    "_fluentd_tag": "ha2union.game.stage",
    "_geoIpCountry": "KR",
    "_market": "google",
    "_os": "android"
  },
  "eventAttributes": {
    "eventTime": "2026-07-20T14:01:01+09:00",
    "level": 10,
    "character_name": "AA",
    "stage_id": "stage_101"
  }
}

hiveAttributes

파이프라인이 자동으로 처리하여 저장하는 영역입니다.

속성명	자료형	설명	예시
`_clientIp`	STRING	로그 전송 시 `client_ip` 또는 `clientIp`를 함께 전송한 경우, 전송된 IP의 마지막 옥텟을 0으로 변경한 값. `client_ip` 또는 `clientIp`를 전송하지 않으면 생성되지 않음	`220.70.82.0`
`_geoIpCountry`	STRING	파이프라인에서 `client_ip` 또는 `clientIp`를 기반으로 판정한 국가 코드 (ISO 3166 alpha-2). `client_ip` 또는 `clientIp`를 전송하지 않으면 생성되지 않음	`KR`
`_dataSource`	STRING	파이프라인에서 판단한 이벤트 로그가 실제로 유입된 경로. 아래 `_dataSource` 상세 참고	`custom_server`
`_fluentd_appid`	STRING	파이프라인에서 판단한 로그 수집기(Fluentd)의 appId	`com.com2us.game.ios`
`_fluentd_sender_ip`	STRING	파이프라인에서 판단한 로그 수집기(Fluentd)의 IP	`43.101.101.33`
`_fluentd_hostaname`	STRING	파이프라인에서 판단한 로그 수집기(Fluentd)의 hostname	`9104813d31ab`
`_fluentd_tag`	STRING	파이프라인에서 판단한 로그 수집기(Fluentd)로 전송된 tag 이름	`ha2union.game.stage`
`_market`	STRING	appId 정보로 애널리틱스에서 판단한 마켓 정보	`google`
`_os`	STRING	appId 정보로 애널리틱스에서 판단한 OS 정보	`android`

_dataSource 상세

_dataSource는 이벤트 로그가 실제로 유입된 경로를 나타내며, 다음 값 중 하나가 자동으로 설정됩니다.

값	설명
`airbridge`	Airbridge를 통해 수집된 이벤트
`appsflyer`	Appsflyer를 통해 수집된 이벤트
`adjust`	Adjust를 통해 수집된 이벤트
`singular`	Singular를 통해 수집된 이벤트
`axyl_server`	Hive Axyl 인증, 빌링 등을 통해 자동으로 수집하는 이벤트
`custom_server`	고객이 서버에서 전송하는 사용자 정의 이벤트
`axyl_custom_sdk`	고객이 Hive Axyl SDK의 이벤트 로그 전송 기능을 통해 전송하는 사용자 정의 이벤트
`custom_except`	이벤트 전환 과정에서 예외적인 케이스로 `eventAttribute`, `hiveAttribute`를 생성하여 전송하는 이벤트

eventAttributes

사용자가 전송한 속성과 SDK가 자동 수집한 속성이 저장되는 영역입니다.

속성명	자료형	설명
`eventTime`	STRING	필수 속성으로 전송된 `eventTime` 원본값
(사용자 정의 속성)	숫자/문자	사용자가 직접 전송한 커스텀 속성
(자동 수집 속성)	속성별 상이	SDK가 자동 수집한 클라이언트 정보 (클라이언트 전송 시)

attributes 주의사항 & Tips

hiveAttributes는 개발사가 직접 값을 설정하는 영역이 아니라 파이프라인이 자동으로 채우는 영역입니다. _clientIp, _dataSource, _fluentd_appid, _fluentd_sender_ip, _fluentd_hostaname, _fluentd_tag, _geoIpCountry, _market, _os 외의 값은 저장되지 않습니다.
사용자 정의 속성과 SDK 자동 수집 속성은 모두 eventAttributes에 함께 저장됩니다. 조회 시 속성명으로 구분해야 합니다.
_dataSource 값으로 이벤트 로그의 전송 경로(SDK/서버 등)를 구분해 조회할 수 있습니다.

데이터 격리

Warning

전송 규칙을 준수하지 않은 이벤트 로그는 정상 테이블(t_raw_event_log)에 저장되지 않고, 격리 테이블(t_raw_event_log_rescue) 에 별도로 저장됩니다. 격리 테이블에는 원본 JSON이 함께 보존되므로, 격리 원인을 파악하고 수정하여 재전송할 수 있습니다.

격리 사유

오류 사유	설명	대응 방법
필수 속성 누락	7개 필수 속성(`userId`, `identifierProvider`, `deviceId`, `appId`, `appIdGroup`, `eventTime`, `eventName`) 중 하나라도 없거나 빈 값	누락된 필수 속성을 포함하여 재전송
예약어 사용	속성명으로 `attributes`, `eventAttributes`, `hiveAttributes`를 사용한 경우 (대소문자 무관)	해당 속성명을 다른 이름으로 변경
허용되지 않는 속성값	속성값이 JSON 객체(`{}`) 또는 JSON 배열(`[]`) 형태인 경우	속성값을 문자열 또는 숫자로 변경
eventTime 형식 오류	`eventTime`이 RFC 3339 형식이 아니거나 파싱할 수 없는 경우	RFC 3339 형식으로 수정 (타임존 포함)
eventTime 범위 초과	`eventTime`이 현재 시각 기준 과거 10년 ~ 미래 5년을 벗어나는 경우	eventTime 값 확인 후 정상 범위로 수정
JSON 파싱 실패	전송된 메시지가 유효한 JSON 형식이 아닌 경우	JSON 형식 검증 후 재전송

격리 테이블 구조

격리된 이벤트 로그는 t_raw_event_log_rescue 테이블에 다음과 같은 구조로 저장 됩니다. 원본 JSON을 파싱할 수 있는 경우에만 각 컬럼에 값이 저장되며, 파싱할 수 없으면 빈 값으로 저장됩니다. 원본은 rawData에서 확인할 수 있습니다.

컬럼명	자료형	설명
`userId`	STRING	전송된 userId
`identifierProvider`	STRING	전송된 identifierProvider
`deviceId`	STRING	전송된 deviceId
`appIdGroup`	STRING	전송된 appIdGroup
`dateTime`	STRING	전송된 eventTime 원본값 (문자열 그대로 저장, TIMESTAMP 아님)
`eventName`	STRING	전송된 eventName
`bigqueryRegistTimestamp`	TIMESTAMP	BigQuery 저장 시각
`checksum`	STRING	파이프라인이 주입하거나 시스템이 생성한 필드(`hiveAttributes` 등)를 모두 제외하고, 고객이 전송한 원본 데이터만으로 생성한 해시값
`rawData`	STRING	전송된 원본 JSON 전체
`errorReason`	STRING	격리 사유 코드. 격리 사유 코드 참고
`errorStackTrace`	STRING	격리 상세 정보 (누락된 필드명 등)

격리 사유 코드

error_code	error_key	발생 조건
100	`JSON_PARSE_ERROR`	JSON 파싱 실패
200	`DATETIME_MISSING`	`dateTime` 필드 없음 또는 빈 값
201	`DATETIME_INVALID`	`dateTime` 파싱 불가
—	`DATASOURCE_MISSING`	`_dataSource` null 또는 미정의 값

격리된 로그 조회 예시

격리된 로그는 BigQuery에서 직접 조회할 수 있습니다. BigQuery로 조회하려면 먼저 BigQuery 권한을 신청해야 합니다.

SELECT
  errorReason,
  errorStackTrace,
  eventName,
  dateTime,
  rawData,
  bigqueryRegistTimestamp
FROM `habq-storage.analytics_N_live.t_raw_event_log_rescue`
WHERE appIdGroup = 'com.sample.test'  -- 사용하는 실제 appIdGroup
LIMIT 100;

더 알아보기

이벤트 속성 전송 — 필수/자동 수집/사용자 정의 속성 상세 규칙
이벤트 로그 전송 — Hive Axyl, Fluentd, HTTP를 통한 전송 방법