문제 해결

SDK를 통합하고 게임을 실행했는데 데이터가 보이지 않습니다. 아래 점검을 순서대로 진행하세요.

얼마나 빨리 도달하나

파이프라인이 예열되면 취합된 이벤트는 수 초 내에 쿼리할 수 있습니다. 유휴 상태 이후의 첫 이벤트는 스토리지 백엔드가 콜드에서 재개하므로 더 오래 걸릴 수 있습니다. 따라서 전송 실패로 판단하기 전에 몇 분 기다리세요. 몇 분이 지나도 아무것도 도달하지 않으면 전송 점검으로 넘어갑니다.

상세 로깅 활성화

기본적으로 SDK는 전송에 대해 거의 로그를 남기지 않으므로 먼저 상세 로깅을 켜세요. 배치가 프로세스를 떠났는지, 서버가 무엇을 반환했는지 알려줍니다.

Unity: TelemetrySDK.Instance.VerboseLogging = true;를 설정합니다(Initialize 전후 모두 반영됩니다). 플러시 성공 시 [Framedash] Flushed N events (HTTP 202)를 기록합니다.
UE5: SDK는 LogFramedash 카테고리로 로그를 남깁니다. -LogCmds="LogFramedash Verbose"로 실행합니다(또는 콘솔에서 Log LogFramedash Verbose 실행). 전송 시 SendBatch: N events -> ...에 이어 HTTP 결과를 기록합니다.
Godot: TelemetrySDK.Instance.VerboseLogging = true;를 설정합니다(Initialize 전후 모두 반영됩니다). 전송 실패 시 재시도 사다리를 기록합니다. 예: [Framedash] Retry 1/3 in 1.0s (HTTP 0).

결과 코드 읽기

기록된 HTTP 상태가 문제 위치를 알려줍니다.

202 — 비동기 처리용으로 수락됨. 요청은 수집 큐에 도달했지만 영구 저장 확인은 아닙니다. 잘못된 이벤트는 후속 검증에서 폐기될 수 있습니다. 아래의 고유 마커로 확인하세요.
0(Godot) 또는 연결 타임아웃 — 전송 계층 실패(DNS, TLS, 프록시, IPv6)이며 API 거부가 아닙니다. 다음 절을 참고하세요.
401 / 403 — API 키가 없거나 events:write scope가 없습니다. Ingest 프리셋 키를 사용하세요.
415 — Content-Type이 잘못되었습니다. 커스텀 전송에만 해당합니다. 취합 엔드포인트는 protobuf만 받습니다. 공식 SDK가 이를 설정해 줍니다.

전송 계층 실패

상태 0이나 반복되는 연결 타임아웃은 요청이 서버에 도달하지 못했음을 뜻합니다. 먼저 같은 머신에서 엔드포인트가 정상인지 확인한 뒤 원인을 분리하세요.

curl -4 -sv https://ingest.framedash.dev/v1/events
curl -6 -sv https://ingest.framedash.dev/v1/events

정상 호스트는 IPv4로 1초 훨씬 이내에 응답합니다(빈 요청은 4xx 구조화 오류를 반환하지만 그래도 도달 가능성은 증명됩니다).

IPv6 문제: SDK는 IPv4를 우선하고 IPv6로 폴백하지만, IPv6 아웃바운드가 깨진 호스트에서는 데이터가 흐르기 전에 짧은 연결 타임아웃이 몇 번 보일 수 있습니다. curl -4는 성공하고 curl -6이 멈춘다면, 해당 인터페이스에서 IPv6를 비활성화하거나 ingest.framedash.dev의 IPv4 hosts 항목을 추가하세요.
DNS 특이점: Godot의 HttpRequest는 자체 비동기 DNS 리졸버를 사용합니다. 그래서 OS 리졸버와 curl이 성공해도 실패(HTTP 0)할 수 있습니다. 불안정하거나 split-horizon인 DNS 경로가 흔한 원인입니다.
프록시: 회사 프록시나 방화벽이 취합 호스트를 차단할 수 있습니다. 같은 머신에서 https://ingest.framedash.dev로의 curl이 실패하면 SDK를 보기 전에 네트워크 경로를 고치세요.

오프라인 큐

Unity와 UE5는 정상 종료 시 또는 일시적인 전송 실패 시 이벤트를 디스크 큐에 기록하고, 다음 초기화 시 게임 루프가 tick하기 시작한 시점에 플러시합니다. CI 타임아웃 kill 같은 강제 종료 시에는 큐가 기록되지 않으므로, 그 시점에 버퍼에 남아 있는 이벤트는 유실됩니다. 정상적으로 종료된 짧은 헤드리스 실행은 이벤트가 큐에서 대기하는 동안 “아무것도 안 보낸” 것처럼 보일 수 있는데, 이는 예상된 동작입니다. 게임을 다시 실행하거나(또는 더 오래 유지하면) 대기 중인 배치가 플러시됩니다. CI에서는 큐에 의존하지 말고 프로세스를 kill하기 전에 로그의 HTTP 2xx 줄을 기다리세요. 자세한 내용은 엔진별 헤드리스 가이드를 참고하세요(Unity, UE5).

Godot에는 디스크 큐가 없습니다. Godot SDK 0.1.5 이상에서 Shutdown()은 상한 2.5초의 블로킹 전송으로 버퍼를 동기적으로 배출합니다. 여전히 오프라인 큐는 없으므로, 이 예산 안에 전송이 실패한 이벤트나 배출이 끝나기 전에 강제 종료된 프로세스에 남은 이벤트는 유실됩니다. 자세한 내용은 Godot 헤드리스 가이드를 참고하세요.

Unity: 배치 모드에서 “Package Manager Cancelled resolving packages”가 발생

git 패키지를 추가한 직후의 Unity 배치 모드 실행이 Package Manager Cancelled resolving packages로 실패할 수 있습니다. 원인은 프로젝트 생성 시 남은 오래된 Temp/UnityLockfile입니다. 에디터를 닫고 Temp/UnityLockfile을 삭제한 뒤 다시 실행하세요.

도달 확인

대시보드 없이 정확한 마커를 확인하려면 data:admin 스코프를 가진 Full 키로 raw SQL을 실행하세요. Read-only 키의 analytics:read 스코프로 집계 분석 API는 조회할 수 있지만 framedash query는 실행할 수 없으며, Ingest 키의 events:write 스코프에는 읽기 권한이 없습니다. 커스텀 전송기를 확인할 때는 ingest_probe_<unique-id>의 <unique-id>를 실행마다 UUID 같은 값으로 바꾸세요. 마커를 재사용하면 이전 이벤트를 현재 실행의 성공으로 오인할 수 있습니다.

# 이 키는 어느 프로젝트에 속하며 유효한가?
framedash auth --api-key-file read.key

# 이번 실행의 고유 마커가 영구 스토리지에 도달했나?(Full 프리셋 키, data:admin scope)
framedash query --api-key-file full.key --project-id <id-from-the-auth-command-above> \
  "SELECT count(), max(timestamp) FROM events WHERE event_name = 'ingest_probe_<unique-id>'"

Ingest(events:write) 키는 자신의 프로젝트를 열거할 수 없으므로 “나는 어느 프로젝트에 쓰고 있는가”는 Ingest 키 자체로는 답할 수 없습니다. 대시보드에서 확인하거나 같은 프로젝트에 Read-only 키를 만드세요. 선택할 수 있는 컬럼은 이벤트 스키마를 참고하세요.

다음 단계

이벤트 스키마: 컬럼과 쿼리 규칙
CLI 레퍼런스: framedash auth와 framedash query
퀵스타트: 통합 흐름

AI 에이전트용: llms.txt