データモデル
Framedash SDK が収集・送信するテレメトリデータの構造を説明します。
各イベントは 1 つの GameTelemetryEvent であり、Protobuf でシリアライズされ、TelemetryBatch として POST /v1/events に送信されます。各イベントは ClickHouse の events テーブルの 1 行に対応します。スキーマは固定です（telemetry.proto で定義）。ゲーム固有のデータは柔軟な attributes / metrics マップに格納できますが、下記の取り込み上限内に収める必要があります。
イベントフィールド
Section titled “イベントフィールド”識別子とコンテキスト
Section titled “識別子とコンテキスト”| フィールド | 型 | 説明 |
|---|---|---|
event_name | string | イベント識別子。例: player_death、または自動イベント session_start / perf_heartbeat。 |
timestamp_us | int64 | イベント発生時刻（Unix エポックのマイクロ秒。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。 |
位置とカメラ
Section titled “位置とカメラ”| フィールド | 型 | 説明 |
|---|---|---|
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 ではなく「未取得」を意味します。
パフォーマンスメトリクス
Section titled “パフォーマンスメトリクス”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 メトリクス
Section titled “ロード時間とディスク I/O メトリクス”Unity SDK 0.1.3、UE5 SDK 0.1.6、Godot SDK 0.1.4 で、自動収集されるパフォーマンス信号が 2 つ追加されました。 どちらも 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：perf_heartbeatのmetricsマップに、前回の heartbeat からの差分として付与されるディスク読み取りカウンター。実際にサンプルが取得できてから初めて現れます。自動ソースは、Unity では Editor / Development Build のみ（AsyncReadManagerMetrics）、UE5 ではオプトイン（bTrackDiskIo）、Godot では手動のみ（ReportIoSample）です。
エンジンごとの API とスレッドの扱いは、各 SDK ガイドを参照してください。
メモリ内訳メトリクス
Section titled “メモリ内訳メトリクス”対応 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 の各ガイドを参照してください。
カスタムデータ
Section titled “カスタムデータ”ゲーム固有のコンテキストは 2 つの柔軟なマップで送信され、スキーマ変更は不要です:
| フィールド | 型 | 説明 |
|---|---|---|
attributes | map<string, string> | 文字列のキーバリュー。例: weapon: "rifle"。COPPA モードでは丸ごと破棄されます。 |
metrics | map<string, double> | 数値の測定値。例: damage: 42.5。 |
取り込み検証上限
Section titled “取り込み検証上限”取り込みパイプラインはデコード後の各イベントを検証します。バッチ内の 1 イベントでも上限外の場合、経路によってリクエスト時に拒否されるか、非同期処理中にバッチ全体が破棄されます。独自 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 entries。key は最大 64 文字、value は最大 512 文字。 |
metrics | 最大 50 entries。key は最大 64 文字、value は有限数。 |
camera_yaw / camera_pitch | 両方存在するか、両方省略。yaw は [0, 360)、pitch は [-90, 90] に正規化されます。 |
バッチエンベロープ
Section titled “バッチエンベロープ”SDK は TelemetryBatch（GameTelemetryEvent のリスト）を送信します。API キーと SDK バージョンはペイロード本文ではなく HTTP ヘッダー（X-API-Key、X-SDK-Version）で送信されます。
独自送信クライアントでは、送信時の HTTP リクエスト本文（gzip 圧縮を使う場合は圧縮後）を 126,000 bytes 以下にしてください。本番取り込みでは、これを超える本文は 413 で拒否されます。公式 SDK はこの上限より十分小さいサイズで flush します。
次のステップ
Section titled “次のステップ”- API リファレンス: REST API でこのデータにアクセス
- ヒートマップ: 位置データの可視化