疑難排解
你整合了 SDK、執行了遊戲，卻沒有資料出現。請依序逐項檢查。
管線預熱後，被取用的事件會在數秒內可查詢。閒置一段時間後的第一個事件可能較慢，因為儲存後端要從冷態恢復，所以在判定傳送失敗前請等待幾分鐘。若幾分鐘後仍無資料到達，再進入傳輸檢查。
啟用詳細記錄
Section titled “啟用詳細記錄”預設情況下 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、Proxy 或 IPv6），而非 API 拒絕。見下一節。
- 401 / 403——API 金鑰缺失或沒有
events:writescope。請使用 Ingest 預設金鑰。 - 415——
Content-Type錯誤。僅與自訂傳送有關；取用端點只接受 protobuf。官方 SDK 會為你設定。
狀態 0 或反覆的連線逾時，代表請求從未到達伺服器。請先從同一台機器確認端點健康，再隔離原因：
curl -4 -sv https://ingest.framedash.dev/v1/eventscurl -6 -sv https://ingest.framedash.dev/v1/events健康的主機會在遠不到一秒內經由 IPv4 回應（裸請求會回傳 4xx 結構化錯誤，這仍能證明可達）。
- IPv6 損壞：SDK 優先 IPv4 並回退到 IPv6，但在 IPv6 出網損壞的主機上，資料開始流動前你可能仍看到一小串連線逾時。若
curl -4成功而curl -6卡住，請在受影響的介面上停用 IPv6，或為ingest.framedash.dev新增一筆 IPv4hosts記錄。 - DNS 怪癖：Godot 的
HttpRequest使用它自己的非同步 DNS 解析器，即使作業系統解析器和curl成功，它也可能失敗（HTTP 0）。通常是不穩定或 split-horizon 的 DNS 路徑所致。 - Proxy：企業 Proxy 或防火牆可能封鎖取用主機。若從同一台機器
curl到https://ingest.framedash.dev失敗，請先修復網路路徑再看 SDK。
Unity 和 UE5 在正常關閉或暫時性傳送失敗時，會把事件寫入磁碟上的佇列，並在下次初始化、遊戲迴圈開始 tick 後清除。強制 kill（例如 CI 逾時 kill）時不會寫入佇列，因此此時仍在緩衝中的事件會遺失。一次正常關閉的短暫無頭執行可能看起來像「什麼都沒送」，而事件其實在佇列中等待，這是預期行為：再執行一次遊戲（或讓它執行更久），排隊的批次就會清除。在 CI 中，請在 kill 行程之前等待記錄中的 HTTP 2xx 行，而不要依賴佇列。細節見各引擎的無頭指南（Unity、UE5）。
Godot 沒有磁碟佇列。在 Godot SDK 0.1.5 及更新版本中，Shutdown() 會透過上限 2.5 秒的阻塞傳送同步排空緩衝。仍然沒有離線佇列，因此在該預算內傳送失敗的事件，或在排空完成前被強制終止的行程中殘留的事件，都會遺失。細節見Godot 無頭指南。
Unity：批次模式下出現 “Package Manager Cancelled resolving packages”
Section titled “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 金鑰。可選取的欄位見事件表結構。