トラブルシューティング

SDK を統合してゲームを実行したのに、データが表示されない。そのときは以下のチェックを順に進めてください。

どれくらいで届くか

パイプラインが温まっていれば、取り込まれたイベントは数秒でクエリできます。アイドル状態のあとの最初のイベントは、ストレージがコールドから再開するため時間がかかることがあります。そのため、送信失敗と判断する前に数分待ってください。数分たっても何も届かないなら、トランスポートのチェックに進みます。

詳細ログを有効にする

既定では SDK は送信についてほとんどログを出しません。まず詳細ログを有効にしてください。バッチがプロセスから出ていったか、サーバーが何を返したかがわかります。

Unity: TelemetrySDK.Instance.VerboseLogging = true; で詳細ログを有効にします（初期化の前後どちらでも反映されます）。フラッシュ成功時は [Framedash] Flushed N events (HTTP 202) を記録します。
UE5: SDK は LogFramedash カテゴリにログを出します。-LogCmds="LogFramedash Verbose" を付けて起動します（またはコンソールで Log LogFramedash Verbose を実行）。送信時は SendBatch: N events -> ... に続けて HTTP の結果を記録します。
Godot: TelemetrySDK.Instance.VerboseLogging = true; で詳細ログを有効にします（初期化の前後どちらでも反映されます）。トランスポート失敗時はリトライの梯子を記録します。例: [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）することがあります。不安定な DNS や split-horizon DNS の経路が典型的な原因です。
プロキシ: 企業のプロキシやファイアウォールが取り込みホストをブロックすることがあります。同じマシンから https://ingest.framedash.dev への curl が失敗するなら、SDK を見る前にネットワーク経路を直してください。

オフラインキュー

Unity と UE5 は、正常なシャットダウン時、または一時的な送信失敗時にイベントをディスク上のキューに書き込み、次の初期化時にゲームループが回り始めた時点でフラッシュします。 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 scope を持つ Full キーで raw SQL を実行します。 Read-only キーの analytics:read scope では集計 API を参照できますが、framedash query は実行できません。Ingest キーの events:write scope にも読み取り権限はありません。独自送信を確認するときは 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）キーは自身のプロジェクトを列挙できないため、「自分はどのプロジェクトに書き込んでいるのか」はそのキー自体からは答えられません。ダッシュボードで確認するか、同じプロジェクトに Read-only キーを作成してください。選択できるカラムはイベントスキーマを参照してください。

次のステップ

イベントスキーマ: カラムとクエリ規則
CLI リファレンス: framedash auth と framedash query
クイックスタート: 統合の流れ

AI エージェント向け: llms.txt