故障排查
你集成了 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、代理或 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 路径所致。 - 代理：企业代理或防火墙可能屏蔽取用主机。若从同一台机器
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 密钥。可选择的列见事件表结构。