コンテンツにスキップ
Framedash Docs
日本語 ja English en 简体中文 zh-cn 繁體中文 zh-tw 한국어 ko

イベントスキーマ

Framedash は生のテレメトリを ClickHouse の events テーブルに保存します。 このテーブルは次の 3 つの経路から SQL で読み取れます。

このページはカラムとバリデータの規則を示します。 Claude Code プラグインがなくてもクエリを書けるようにするためのものです。

アクセスと scope

Section titled “アクセスと scope”

raw SQL には data:admin scope を持つ API キー（Full プリセット）が必要です。 Read-only キーは組み込みの分析エンドポイントと MCP ツールを使えますが、raw な query 経路は使えません。 Ingest（events:write）キーは設計上クエリを実行できず、自身のプロジェクトを列挙することもできません。

クエリ規則

Section titled “クエリ規則”

クエリはバリデーションされ、プロジェクト分離を強制するよう書き換えられ、読み取り専用の接続で実行されます。 バリデータは次を強制します。

  • SELECT のみ。INSERT / UPDATE / DELETE / DROP / ALTER / CREATE / TRUNCATE / SYSTEM / OPTIMIZE / KILL、UNION / EXCEPT / INTERSECT は不可。
  • FROM / JOIN に書けるテーブルは 2 つだけ。events（生イベント）と daily_sessions_project_mv（日次セッションの事前集計）。FROM events と素直に書けば、分離フィルタは自動で注入されます。
  • SQL 内で tenant_id や project_id を参照しない。これらは自動でスコープされ、直接参照すると拒否されます。
  • 文字列リテラルはシングルクォートのみ。ダブルクォートとバッククォートは拒否されます。
  • SETTINGS / FORMAT / GLOBAL 句は不可。IN (SELECT ...) と IN ('a','b') は可、IN some_table は不可。
  • トップレベルの LIMIT を省くと自動で付与されます。

結果は { "rows": [ { "col": "value" } ], "rowCount": 123 } の形です。CLI と MCP ツールはこの形のまま返します。REST エンドポイントを直接呼ぶ場合は、標準の API エンベロープで包まれます: { "success": true, "data": { "rows": [...], "rowCount": 123 } }。 MCP の query ツールは最大 1000 行、REST エンドポイントと CLI は最大 10000 行です。 より大きな抽出では LIMIT ... OFFSET ... でページングするか、timestamp の範囲を絞ってください。

カラム

Section titled “カラム”
カラム型補足
event_nameStringイベント名。例: player_death、level_start、perf_heartbeat
timestampDateTime64(6)イベント時刻（UTC）
session_idStringプレイセッション ID
player_idString安定したプレイヤー/デバイス ID
position_x, position_y, position_zFloat32ワールド座標
map_idStringマップ/レベル識別子
fpsFloat32フレームレート（perf イベント）
frame_time_msFloat32フレームタイム ms（perf イベント）
memory_used_bytesInt64メモリ量 byte（perf イベント）
gpu_time_msFloat32GPU 時間 ms（perf イベント）
game_thread_msFloat32ゲームスレッド時間 ms
render_thread_msFloat32レンダースレッド時間 ms
camera_yaw, camera_pitchNullable(Float32)カメラの向き
sourceStringSDK 自身の内部イベント（session_start、perf_heartbeat）は automated。あなたの Track(...) 呼び出しは player。CI の指標ではありません（下記の規約を参照）
build_idStringビルド識別子（perf-diff の候補）
platformString例: windows、android
engine_versionStringエンジン/ビルドのバージョン文字列
attributesMap(String, String)カスタムの文字列属性
metricsMap(String, Float64)カスタムの数値メトリクス

Map 型のカラムはブラケットでアクセスします。attributes['ci.branch']、metrics['score'] の形です。

server_timestamp というカラムはありません。 イベント時刻には timestamp を使ってください。 存在しないカラムを指定するとクエリエラーになるため、先に上の名前を確認してください。 却下されたクエリは HTTP 400 で ClickHouse の診断メッセージ（未知のカラム、テーブル、関数、構文エラー、型の不一致、禁止された操作）を返し、インフラ側の障害のみ 500 を返します。

規約

Section titled “規約”
  • 自動のパフォーマンスイベントは perf_heartbeat です。perf のクエリは WHERE event_name = 'perf_heartbeat' で絞ってください。すべてのイベントが fps / frame_time_ms を持つわけではありません。
  • source = 'automated' は SDK 自身の内部イベント（session_start、perf_heartbeat）を示すもので、あなたの Track(...) 呼び出しと区別するためのものです。CI かどうかに関わらず全セッションで設定されるため、これ単体では CI 実行を識別できません。
  • CI プロファイリングデータを絞り込むには、source ではなく build_id または attributes['ci.*'] タグ（BeginAutomatedSession / BeginAutomatedSessionFromEnvironment が設定）を使ってください。
  • CI のメタデータは attributes に載ります。attributes['ci.branch']、attributes['ci.commit']、attributes['ci.scenario'] と、第一級の build_id カラムです。
  • イベント名は Track(...) で自分が選ぶ自由な文字列です。公式 SDK のサンプルは snake_case（player_death、level_start）を使います。タイトル全体で一つの規約に揃えてください。
  • timestamp は常に範囲を絞ってください。テーブルは日付でパーティション分割されているため、範囲を絞るとパーティションが刈り込まれて高速になります。

例

Section titled “例”

今日のアクティブプレイヤー数。

SELECT uniqExact(player_id) AS dau
FROM events
WHERE timestamp >= today()

直近 7 日のイベント名別の件数。

SELECT event_name, count() AS events, uniqExact(session_id) AS sessions
FROM events
WHERE timestamp >= today() - 7
GROUP BY event_name
ORDER BY events DESC

ビルドごとのパフォーマンスパーセンタイル。

SELECT build_id,
       count() AS samples,
       round(quantile(0.50)(fps), 1) AS fps_p50,
       round(quantile(0.95)(frame_time_ms), 2) AS frametime_p95_ms
FROM events
WHERE event_name = 'perf_heartbeat'
  AND timestamp >= today() - 14
GROUP BY build_id
ORDER BY samples DESC

次のステップ

Section titled “次のステップ”
AI エージェント向け: llms.txt