Databricks Events

개요 Labs

플레이어 이벤트가 이미 Databricks lakehouse에 있다면, 별도의 내보내기 작업 없이 FirstLook에 연결할 수 있습니다. FirstLook은 Delta Sharing 수신자(Databricks에서는 OpenSharing이라고도 부르며, 동일한 프로토콜입니다)로서 워크스페이스에 연결합니다. 이벤트 테이블을 공유하면 FirstLook은 Databricks에 데이터가 도착한 후 몇 분 이내에 새로운 행을 가져옵니다. 수집된 이벤트는 다음 예약된 집계 갱신(일반적으로 1시간 이내)이 완료된 후 분석 차트에 표시됩니다.

수집된 이벤트는 S3 Events 페이지에서 설명하는 S3 파이프라인과 동일하게, FirstLook SDK를 통해 수집된 데이터와 함께 분석, 리텐션 차트, 플레이어 프로필에 반영됩니다. S3 방식과 달리, 예약해야 할 내보내기 작업도 없고 맞춰야 할 CSV 형식도 없으며, 읽기 작업이 Databricks 컴퓨팅 리소스를 소비하지 않습니다.

주요 기능

공유된 테이블을 감시하여 약 1분마다 새 버전을 확인하고, 마지막으로 처리한 버전 이후 추가된 행만 읽습니다.
기존 데이터를 먼저 가져옵니다. 증분 읽기로 전환하기 전에 기존 행(선택적으로 지정한 시작 날짜부터)을 수집합니다.
플랫폼 ID를 통해 플레이어 신원을 확인하여 통합된 FirstLook 플레이어 프로필로 연결하고, 처음 나타나는 플랫폼 ID에 대해 새 플레이어 레코드를 생성합니다.
수집 상태를 대시보드에 표시하여 수집 실행 로그를 제공하므로 무엇이 언제 가져와졌는지 항상 확인할 수 있습니다.

접근 방식

FirstLook은 오픈 수신자입니다. 사용자가 생성한 베어러 토큰으로 워크스페이스의 공유 서버에 인증하고, 테이블의 데이터 파일에 대한 단기 다운로드 링크를 수신하며, 워크스페이스나 스토리지에 대한 쓰기 권한은 없습니다. 자격 증명은 언제든지 취소하거나 교체할 수 있습니다.

테이블 요구 사항

Delta Sharing은 FirstLook과 같은 외부 수신자에게 테이블을 제공할 때 몇 가지 조건을 적용합니다. 테이블 생성 시에 이 요구 사항을 충족하세요. 일부는 나중에 수정하기 까다롭습니다.

요구 사항	이유
스트리밍 테이블이나 구체화된 뷰가 아닌 일반 Delta 테이블	파이프라인 관리 객체(Lakeflow / Delta Live Tables 출력)는 외부 수신자에게 스냅샷 전용으로 제공됩니다. 버전 기록과 변경 피드를 사용할 수 없습니다. 이벤트가 여기에 있다면, 파이프라인에서 최종 추가 전용 싱크로 일반 Delta 테이블을 추가하고 그것을 공유하세요.
생성 시 변경 데이터 피드 활성화 (`delta.enableChangeDataFeed = true`)	이 설정이 있어야 FirstLook이 매번 테이블 전체를 재스캔하지 않고 매분 새 행만 읽을 수 있습니다. 나중에 활성화하면 이전 버전을 읽을 수 없으므로 처음부터 설정하세요.
생성 시 삭제 벡터 비활성화 (`delta.enableDeletionVectors = false`)	최신 Databricks 런타임은 삭제 벡터를 기본으로 활성화하지만, 이 기능이 있는 테이블은 FirstLook이 읽는 공유 형식으로 제공될 수 없으며, 나중에 속성을 끄더라도 테이블 기록에 남습니다. 추가 전용 이벤트 테이블에서는 삭제 벡터가 필요하지 않습니다.
대상 파일 크기 설정 (`delta.targetFileSize = '256mb'`)	FirstLook은 테이블의 데이터 파일을 통째로 다운로드하여 처리하며 파일당 크기 제한이 있습니다. Databricks의 `OPTIMIZE`는 기본적으로 파일을 ~1 GB 크기로 압축하는데, 이는 제한을 초과할 수 있습니다. 이 속성을 설정하면 압축된 파일을 제한 이하로 유지합니다.
사용자 자신의 클라우드 스토리지(S3, ADLS 또는 GCS)에 있는 데이터	Delta Sharing은 스토리지에 대한 사전 서명 링크를 생성하여 외부 수신자에게 제공합니다. Databricks 관리 “기본 스토리지”(Free Edition 및 서버리스 기본 워크스페이스)의 테이블은 외부에서 공유할 수 없습니다. 명시적인 `LOCATION`이 있는 외부 테이블을 사용하거나, 관리 위치가 사용자 버킷인 카탈로그를 사용하세요.

Unity Catalog가 활성화된 워크스페이스와 공유 및 수신자를 생성할 수 있는 권한이 필요합니다.

1. 이벤트 테이블 생성

아래의 참조 테이블은 다섯 가지 요구 사항을 모두 충족합니다. 스키마를 카운터 또는 기간 계약(테이블 스키마 참조)에 맞게 조정하고, 위치를 사용자 버킷으로 변경하세요.

CREATE TABLE game_analytics.player_counter_events (
  steam_id      STRING,     -- exactly one player identity column
  session_id    STRING,     -- UUID
  timestamp     TIMESTAMP,
  counter_name  STRING,     -- e.g. 'match.kills'
  counter_value INT,
  build_version STRING      -- optional
)
LOCATION 's3://your-bucket/firstlook/player_counter_events'
TBLPROPERTIES (
  delta.enableChangeDataFeed  = true,
  delta.enableDeletionVectors = false,
  delta.targetFileSize        = '256mb'
);

이벤트 테이블을 포함하는 공유를 생성하고, FirstLook을 나타내는 수신자를 생성한 후 접근 권한을 부여합니다. WITH HISTORY 절은 증분 읽기를 가능하게 하므로 생략하지 마세요.

CREATE SHARE firstlook_share;

ALTER SHARE firstlook_share
  ADD TABLE game_analytics.player_counter_events WITH HISTORY;

CREATE RECIPIENT firstlook;

GRANT SELECT ON SHARE firstlook_share TO RECIPIENT firstlook;

수신자를 생성하면 활성화 링크가 생성되며, 여기서 자격 증명 파일을 다운로드합니다. 이 파일은 공유 엔드포인트와 베어러 토큰이 담긴 소형 JSON 파일입니다. 비밀번호처럼 취급하세요. Databricks는 수신자에 토큰 만료를 설정할 것을 권장합니다. 교체 방법은 자격 증명 수명 주기를 참조하세요.

3. 대시보드에서 구성

게임 대시보드에서 Configuration > Databricks Events로 이동하여 다음을 입력합니다:

Credential File — 다운로드한 자격 증명 파일의 전체 내용을 붙여넣습니다.
Tables — 공유된 테이블마다 한 행씩: 공유, 스키마, 테이블 이름(예: firstlook_share / game_analytics / player_counter_events).
Backfill from — (선택 사항, 테이블별) 가져올 가장 이른 이벤트 날짜. 비워두면 테이블의 전체 기록을 가져옵니다.
Enabled — 언제든지 수집을 켜거나 끌 수 있습니다.

저장하면 FirstLook은 공유 서버에서 즉시 모든 테이블을 검증하여 스키마 계약, 변경 데이터 피드 지원, 테스트 읽기를 확인하므로, 잘못 구성된 테이블은 즉시 구체적인 오류를 표시합니다. 검증된 각 테이블에는 *“Validated: counter events, steam_id identity — awaiting first ingestion”*과 같은 확인 메시지가 표시되며, 첫 번째 가져오기는 1분 이내에 시작됩니다.

테이블 스키마

공유된 각 테이블은 카운터 테이블(숫자 값이 있는 이산 이벤트) 또는 기간 테이블(시간이 측정되는 활동) 중 하나입니다. 유형은 열을 기반으로 감지되며, 테이블당 하나의 유형만 허용됩니다. 추가 열은 무시되므로, 추가 필드가 있는 테이블도 공유할 수 있습니다.

모든 테이블에는 S3 파이프라인이 지원하는 것과 동일한 집합에서 선택한 정확히 하나의 플레이어 식별자 열이 포함되어야 합니다. 지원되는 식별자는 플레이어 신원 열 목록을, 행이 플레이어 프로필로 변환되는 방식은 신원 확인을 참조하세요.

카운터 테이블

열	유형	설명
(identifier)	`STRING`	플레이어 신원 열 하나.
`session_id`	`STRING` (UUID)	플레이 세션의 이벤트를 그룹화합니다.
`timestamp`	`TIMESTAMP`	이벤트가 발생한 시각.
`counter_name`	`STRING`	점으로 구분된 이벤트 이름(예: `match.kills`). 파라미터를 기록하려면 `#<parameter>`를 추가합니다(예: `level.started#forest_3`).
`counter_value`	`INT`	이벤트 값(예: 킬 수).
`build_version`	`STRING`	(선택 사항) 이벤트를 생성한 게임 빌드.

기간 테이블

열	유형	설명
(identifier)	`STRING`	플레이어 신원 열 하나.
`session_id`	`STRING` (UUID)	플레이 세션의 이벤트를 그룹화합니다.
`start_time`	`TIMESTAMP`	활동이 시작된 시각.
`end_time`	`TIMESTAMP`	활동이 종료된 시각.
`duration_name`	`STRING`	점으로 구분된 이벤트 이름(예: `match.round`).

수집 동작 방식

첫 번째 가져오기, 이후 증분 처리

테이블이 처음 검증되면 FirstLook은 스냅샷을 읽고(전체 기록 또는 Backfill from 날짜 이후의 모든 데이터), 그 후 테이블의 Delta 버전을 추적하여 각 변경마다 새로 추가된 행만 읽습니다. 위의 delta.targetFileSize 지침을 따르는 경우, 대용량 기록도 한 번에 가져옵니다.

이벤트는 추가 전용

FirstLook은 삽입된 행만 수집합니다. 테이블의 업데이트와 삭제는 무시됩니다. 플레이어 이벤트는 변경 불가능한 사실로 취급되므로, 수정이 필요하면 기존 행을 편집하는 대신 새 이벤트로 추가해야 합니다. 두 가지 결과가 있습니다:

전체 재로드는 안전합니다. 업스트림 작업이 테이블을 재작성하더라도(INSERT OVERWRITE, 재실행된 파이프라인), FirstLook의 중복 감지가 재삽입된 행을 처리하므로 이중 집계가 발생하지 않습니다. 낭비적이지만 무해합니다.
Databricks에서 행을 삭제해도 FirstLook에서 이벤트가 제거되지 않습니다.

차트에 이벤트가 표시되는 시점

가져온 행은 실행이 완료되는 즉시 저장되며, 분석 차트는 다음 예약된 집계 갱신(일반적으로 1시간 이내)에 반영됩니다. 가져오기는 완료되었지만 차트가 아직 업데이트되지 않은 상태는 정상입니다.

자격 증명 수명 주기

Delta Sharing 베어러 토큰은 일반적으로 만료 시간이 설정됩니다. FirstLook은 자격 증명 파일에서 만료 시간을 읽고, 만료 14일 전부터 구성 페이지에 배너를 표시합니다. 읽기가 반복적으로 실패하면 수집이 일시 중지됩니다.

교체하려면 Databricks에서 수신자에 대한 새 자격 증명 파일을 생성하고(ALTER RECIPIENT firstlook ROTATE TOKEN 또는 UI를 통해) 구성 페이지의 Credential 섹션에 붙여넣으세요. 테이블 구성과 가져오기 기록은 그대로 유지되며, 자격 증명 오류로 인해 수집이 일시 중지된 경우 자동으로 재개됩니다.