데이터 모델

Framedash SDK가 수집하고 전송하는 텔레메트리 데이터의 구조를 설명합니다.

각 이벤트는 하나의 GameTelemetryEvent이며, Protobuf로 직렬화되어 TelemetryBatch로 POST /v1/events에 전송됩니다. 각 이벤트는 ClickHouse events 테이블의 한 행에 대응합니다. 스키마는 고정되어 있습니다(telemetry.proto에 정의). 게임 고유 데이터는 유연한 attributes / metrics 맵에 저장할 수 있지만, 아래 ingest 제한 안에 있어야 합니다.

이벤트 필드

식별자 및 컨텍스트

필드	타입	설명
event_name	string	이벤트 식별자. 예: player_death, 또는 자동 이벤트 session_start / perf_heartbeat.
timestamp_us	int64	이벤트 발생 시각(Unix epoch 마이크로초. DateTime64(6)로 저장).
session_id	string	게임 세션 식별자.
player_id	string	명시적 플레이어 식별자. SDK가 수집하는 유일한 PII. COPPA 모드에서는 제거됩니다.
map_id	string	공간 분석용 맵 / 레벨 식별자.
build_id	string	빌드 버전.
platform	string	엔진이 보고하는 플랫폼 이름(Unity는 Application.platform, UE는 IniPlatformName, Godot은 OS.GetName()).
engine_version	string	엔진 버전(Unity는 Application.unityVersion, UE는 FEngineVersion, Godot은 Engine.GetVersionInfo()["string"]).
source	enum	이벤트 출처: player / automated / unspecified.

참고

timestamp_us는 이벤트 페이로드에 담기는 Protobuf 필드 이름입니다(int64, 마이크로초). SQL로 텔레메트리를 조회할 때(POST /v1/query, CLI, 또는 MCP query 도구)는 ClickHouse 컬럼 이름이 timestamp이고 타입은 DateTime64(6)입니다. 쿼리에서는 timestamp_us가 아니라 timestamp를 선택하세요. 조회 가능한 전체 컬럼 목록은 이벤트 스키마를 참고하세요.

위치 및 카메라

필드	타입	설명
position	Vector3(x, y, z float)	월드 공간 위치. position_x / position_y / position_z로 저장.
camera_yaw	float(선택)	카메라 수평 회전(도). 0 = 북쪽, 시계 방향, 범위 [0, 360). SDK가 카메라를 캡처하지 않으면 없음.
camera_pitch	float(선택)	카메라 수직 회전(도). -90 = 정면 아래, +90 = 정면 위.

camera_yaw와 camera_pitch는 함께 전송되거나 전혀 전송되지 않습니다. 값이 없으면 0이 아니라 “캡처되지 않음”을 의미합니다.

퍼포먼스 메트릭

SDK가 자동으로 수집하며, 특히 10초마다 전송되는 perf_heartbeat 이벤트에 포함됩니다:

필드	타입	단위 / 비고
fps	float	초당 프레임
frame_time_ms	float	밀리초
gpu_time_ms	float	밀리초
game_thread_ms	float	CPU 게임 스레드 시간(ms). 0 = 미수집
render_thread_ms	float	CPU 렌더 스레드 시간(ms). 0 = 미수집
memory_used_bytes	int64	바이트

로드 시간과 디스크 I/O 메트릭

Unity SDK 0.1.3, UE5 SDK 0.1.6, Godot SDK 0.1.4에서 자동 수집되는 성능 신호가 두 가지 추가되었습니다. 둘 다 perf-diff(빌드 비교) 회귀 게이트와 대시보드 차트에 사용됩니다.

• map_load: BeginMapLoad / EndMapLoad 또는 ReportMapLoad가 맵이나 레벨 로드가 끝날 때 발생시키는 전용 자동 이벤트입니다. metrics["load_time_ms"]와 attributes["map_name"]를 담고, 의도적으로 map_id를 비워 두어 공간 히트맵과 활성화 게이트에서 제외됩니다.
• io.read_bytes / io.read_time_ms / io.read_ops: 이전 heartbeat 이후의 델타로 perf_heartbeat의 metrics 맵에 첨부되는 디스크 읽기 카운터입니다. 실제 샘플이 들어온 뒤에야 나타납니다. 자동 소스는 Unity에서는 Editor / Development Build 전용(AsyncReadManagerMetrics), UE5에서는 옵트인(bTrackDiskIo), Godot에서는 수동 전용(ReportIoSample)입니다.

엔진별 API와 스레드 규칙은 각 SDK 가이드를 참고하세요.

메모리 카테고리 메트릭

지원되는 SDK는 메모리 카테고리별 사용량을 mem.* 메트릭으로 perf_heartbeat와 위치가 지정된 이벤트에 첨부합니다. 사용할 수 있는 키와 수집 방식은 엔진마다 다릅니다.

• UE5 SDK 0.1.7 이상: mem.vram과 LLM에 의존하는 mem.textures / mem.meshes / mem.audio. 셋 다 옵트인(bTrackMemoryDetail, 기본값 꺼짐)이며, mem.vram은 LLM이 필요 없지만 헤드리스 / -nullrhi 실행에서는 첨부되지 않습니다(이때는 0이 아니라 키 없음).
• Unity SDK 0.1.4 이상: mem.vram과 mem.heap. 옵트인 없이 자동으로 수집됩니다.
• Godot SDK 0.1.5 이상: mem.vram, mem.textures, mem.buffers. 옵트인 없이 자동으로 수집됩니다.

셋 다 metrics 맵에 실리며, 추적되지 않은 카테고리는 키 자체가 없습니다(“수집되지 않음”을 뜻하며, 수집된 0과 구분됩니다). mem.vram은 perf-diff(빌드 비교)의 비교 지표이기도 합니다. 엔진별 자세한 내용은 UE5 SDK, Unity SDK, Godot SDK 가이드를 참고하세요.

커스텀 데이터

게임 고유 컨텍스트는 두 개의 유연한 맵으로 전송되며, 스키마 변경이 필요 없습니다:

필드	타입	설명
attributes	map<string, string>	문자열 키-값 쌍. 예: weapon: "rifle". COPPA 모드에서는 전부 삭제됩니다.
metrics	map<string, double>	숫자 측정값. 예: damage: 42.5.

Ingest 검증 제한

ingest 파이프라인은 디코딩된 모든 이벤트를 검증합니다. 배치 안의 이벤트 하나라도 제한을 벗어나면 경로에 따라 요청 시점에 거부되거나 비동기 처리 중 배치 전체가 삭제될 수 있습니다. 커스텀 SDK나 원시 Protobuf 전송기는 flush 전에 값을 클램프해야 합니다. 공식 Unity, UE5, Godot SDK는 클라이언트에서 이 클램프를 적용합니다.

필드	제한
timestamp_us	최근 30일 이내이며, 미래 48시간을 넘지 않아야 합니다.
event_name / session_id	필수이며 비어 있으면 안 됩니다. event_name은 최대 128자, session_id는 최대 64자입니다.
player_id, map_id, build_id	각각 최대 128자입니다.
source, platform, engine_version	각각 최대 64자입니다.
position_x / position_y / position_z	유한한 숫자이며 절댓값은 1e9 이하여야 합니다.
fps	0부터 1000까지의 유한한 숫자입니다.
frame_time_ms / gpu_time_ms / game_thread_ms / render_thread_ms	0부터 10000까지의 유한한 밀리초 값입니다.
memory_used_bytes	0부터 64 GiB까지의 정수입니다.
attributes	최대 50개 항목. 키는 최대 64자, 값은 최대 512자입니다.
metrics	최대 50개 항목. 키는 최대 64자, 값은 유한한 숫자여야 합니다.
camera_yaw / camera_pitch	둘 다 있거나 둘 다 없어야 합니다. yaw는 [0, 360), pitch는 [-90, 90]로 정규화됩니다.

배치 엔벨로프

SDK는 TelemetryBatch(즉 GameTelemetryEvent 목록)를 전송합니다. API 키와 SDK 버전은 페이로드 본문이 아니라 HTTP 헤더(X-API-Key, X-SDK-Version)로 전송됩니다.

커스텀 전송기는 전송되는 HTTP 요청 본문(gzip 압축을 사용하는 경우 압축 후)을 126,000 bytes 이하로 유지해야 합니다. 프로덕션 ingest에서 더 큰 본문은 413으로 거부됩니다. 공식 SDK는 이 상한보다 충분히 작은 크기에서 flush합니다.

다음 단계

• API 레퍼런스: REST API로 이 데이터에 접근
• 히트맵: 위치 데이터의 시각화