イベントログの保存構造と取り込み失敗データを確認する：イベントログ送信第4回

Hive Analytics · 2026年10月29日 · 読了目安 5分

Hive Analyticsに送信したイベントのうち、収集基準を満たしたイベントは会社ごとのBigQueryデータセットのt_raw_event_logに、基準を満たさないイベントは元のJSONと隔離理由とともにt_raw_event_log_rescueに保存されます。通常テーブルでイベントが見つからない場合は、rescueテーブルのerrorReason、errorStackTrace、rawDataで隔離の原因を確認します。たとえばeventTimeがRFC 3339形式に従っていない場合、201（DATETIME_INVALID）エラーで隔離されます。その場合は時刻の形式を修正してイベントを再送信し、通常テーブルに保存されたことを確認します。

送信したイベントの保存結果を確認する

「ゲームデータをイベントログとして送信する：イベントログ送信第3回」では、実際のゲームデータをイベントログとして送信する方法を紹介しました。今回は、送信したイベントの保存構造を確認し、正常に保存されなかったイベントの隔離理由と確認方法を説明します。

ログ送信機能を適用した後は、イベントが正常に保存されたかを確認する必要があります。必須プロパティや値の形式などの収集基準を満たしたイベントは通常テーブルに保存されますが、基準を満たさないイベントは別の隔離テーブルに保存されます。

送信したイベントが通常テーブルに見つからない場合は、単なる収集の遅れと判断せず、隔離されていないか、その原因は何かをあわせて確認する必要があります。

Hive Analyticsのイベント保存構造

イベントデータ

Hive Analyticsで正常に収集されたイベントは、会社ごとのBigQueryデータセットのt_raw_event_logテーブルに保存されます。このテーブルはdateTimeを基準に日単位でパーティション分割され、イベントの基本情報とプロパティをあわせて保存します。

フィールド	データ型	説明	生成方法
`userId`	STRING	アカウント単位でユーザーを識別する値	必須プロパティとして送信
`identifierProvider`	STRING	ユーザー識別子を発行したシステム	必須プロパティとして送信
`deviceId`	STRING	デバイス単位でユーザーを識別する値	必須プロパティとして送信
`appId`	STRING	イベントが発生したアプリを識別する値	必須プロパティとして送信
`appIdGroup`	STRING	複数のアプリを1つのゲーム（プロジェクト）としてまとめる値	`appId`をもとに自動生成
`dateTime`	TIMESTAMP	`eventTime`をUTCに変換したイベント発生時刻	`eventTime`を解析して自動生成
`eventName`	STRING	イベントを区別する名前	必須プロパティとして送信
`checksum`	STRING	イベントデータから生成したハッシュ値	イベントデータをもとに自動生成
`bigqueryRegistTimestamp`	TIMESTAMP	イベントがBigQueryに保存された時刻	保存時に自動生成
`attributes`	JSON	カスタムプロパティと自動収集プロパティが保存される領域	送信したプロパティを構造に合わせて自動生成

contents_successイベントが正常に収集されると、次のようにイベントの基本情報とプロパティ値が1行に保存されます。同じイベントが再送信されると、重複データが保存されることがあります。元データを直接照会する場合は、checksumを基準に重複を除外することをおすすめします。

BigQueryでt_raw_event_logを照会し、contents_successイベントの基本情報とattributesが1行に保存された結果画面 — `t_raw_event_log`にイベントの基本情報とプロパティ値が1行に保存されています。

イベントプロパティの保存構造

イベントとともに送信されたプロパティや自動収集されたプロパティは、attributesフィールドにJSON形式で保存されます。attributesの内部は、プロパティの収集方法によってhiveAttributesとeventAttributesに分かれます。

区分	説明	主な値
`hiveAttributes`	Hive Analyticsのデータ処理過程で自動的に追加されるプロパティ	`_dataSource`
`eventAttributes`	イベントとともに送信されたプロパティ、またはクライアントで自動収集されたプロパティ	元の`eventTime`、カスタムプロパティ、SDK自動収集プロパティ

hiveAttributesの_dataSourceを見ると、Hive SDKやゲームサーバーなど、イベントが送信された経路を区別できます。eventAttributesでは、ゲームから直接送信したカスタムプロパティとその実際の値を確認できます。Hive SDKで自動収集したクライアントプロパティもこの領域に含まれます。詳しくは、Hive開発者サイトのイベント保存構造をご覧ください。

隔離データ

必須プロパティや値の形式などの収集基準を満たさないイベントは、取り込みに失敗し、会社ごとのBigQueryデータセットのt_raw_event_log_rescueに隔離されます。隔離テーブルには、送信した元のJSONと隔離理由があわせて保存されます。通常テーブルでイベントが確認できない場合は、rescueテーブルで該当イベントが隔離されていないかを確認します。

主な隔離理由	説明
必須プロパティの欠落	ログ送信に必要なプロパティがない、または値が空になっている
予約語の使用	カスタムプロパティ名として`attributes`、`eventAttributes`、`hiveAttributes`を使用している、または`_`で始まるプロパティ名を使用している
サポートされていないデータ型	カスタムプロパティの値としてJSONオブジェクトまたは配列を送信している
不正な`eventTime`形式	`eventTime`をタイムゾーンを含むRFC 3339形式として解釈できない
`eventTime`の許容範囲超過	イベント発生時刻が収集できる範囲（過去10年から未来5年まで）を外れている
JSON形式エラー	送信したログを正しいJSONとして解釈できない

プロパティ名に使用する予約語は、英字の大文字と小文字を区別しません。たとえばAttributesやHIVEATTRIBUTESも予約語として扱われるため、カスタムプロパティ名として使用しないでください。

隔離テーブルの保存構造

t_raw_event_log_rescueには、元のログから読み取れるイベントの基本情報、元データ、隔離の原因が保存されます。

フィールド	データ型	説明
`userId`	STRING	元のログから読み取れるユーザー識別子
`identifierProvider`	STRING	ユーザー識別子を発行したシステム
`deviceId`	STRING	元のログから読み取れるデバイス識別子
`appIdGroup`	STRING	イベントが属するゲーム（プロジェクト）の識別値
`dateTime`	STRING	送信された元の`eventTime`の値
`eventName`	STRING	イベントを区別する名前
`bigqueryRegistTimestamp`	TIMESTAMP	イベントがBigQueryに保存された時刻
`checksum`	STRING	イベントデータから生成したハッシュ値
`rawData`	STRING	送信したイベントの元のJSON
`errorReason`	STRING	イベントが隔離された原因を示すコード
`errorStackTrace`	STRING	欠落したフィールドなど、隔離の原因に関する詳細情報

通常テーブルのdateTimeには、eventTimeを変換したTIMESTAMP値が保存されます。隔離テーブルのdateTimeには、送信した値の問題を確認できるよう、元のeventTimeが文字列のまま保存されます。

contents_successの隔離理由を確認する

contents_successイベントを送信したときに隔離されたデータを、BigQueryで確認する手順です。

BigQueryの照会権限の申請
隔離理由を確認するには、BigQueryで元データを照会する権限が必要です。BigQueryを利用するには、Hive Analyticsの管理者権限を取得したうえで、Hive AnalyticsのアカウントメニューからBigQueryの照会権限を申請します。権限が適用されたら、Google CloudのBigQueryコンソールにアクセスし、エクスプローラーで照会権限が付与されたHive Analyticsのプロジェクトと会社ごとのデータセットを確認します。その後、該当データセットのt_raw_event_log_rescueを照会します。BigQueryの使い方について詳しくは、Hive開発者サイトのBigQuery 設定をご覧ください。

BigQueryでt_raw_event_log_rescueのerrorReason、errorStackTrace、rawDataを照会した画面 — 隔離データを照会し、エラーコードと元データを確認します。

BigQueryでt_raw_event_log_rescueを照会すると、errorReasonに201と表示されました。errorStackTraceとrawDataを確認すると、eventTimeが2026-10-26T17:51:57+09:00+09:00として送信され、タイムゾーンが重複していることがわかります。この値はRFC 3339形式に合わないため、保存用のdateTimeに解析できません。

隔離コードと対処方法

errorReason	対処方法
100	送信したメッセージが有効なJSONではありません。JSON形式を検証してから送信します。
200	`eventTime`フィールドをタイムゾーンを含むRFC 3339形式で送信します。また、`eventTime`の時刻が許容範囲（過去10年〜未来5年）に収まるように送信します。
201	`eventTime`フィールドをタイムゾーンを含むRFC 3339形式で送信します。
300	`attributes`、`eventAttributes`、`hiveAttributes`はパイプラインが自動生成する予約フィールドのため、イベントに直接含めません。`_`で始まるフィールド名はパイプラインの内部用に予約されているため、使用しません。
400	必須フィールド（`userId`、`identifierProvider`、`deviceId`、`appId`、`eventName`、`eventTime`）がすべて含まれているかを確認してから送信します。
401	イベントプロパティの値にJSONオブジェクト（`{}`）または配列（`[]`）が含まれています。すべてのプロパティは1階層のフラットな構造（文字列/数値）で送信します。JSON文字列（`"{...}"`、`"[...]"`）も拒否されます。

正しいeventTimeの形式と許容範囲を確認したうえで、2026-10-26T17:51:57+09:00のようにタイムゾーンを1回だけ含むよう修正して再送信します。その後、同じ条件でデータを照会し、修正したイベントがt_raw_event_logに正常に保存されたことを確認します。

Hive Analyticsを始める

正常に収集されたイベントはt_raw_event_logに保存され、収集基準を満たさないイベントは元データとエラー情報を含めてt_raw_event_log_rescueに隔離されます。2つのテーブルをあわせて確認すれば、イベントの保存結果を区別し、正常に収集されなかったログの原因を見つけて送信コードを修正できます。

Hive Analyticsは、収集したゲームイベントを分析し、正常に処理されなかったイベントログの隔離理由と元データを確認して問題の原因を把握できる、ゲーム専門のアナリティクスソリューションです。今すぐHive AnalyticsのBigQueryデータセットで、イベントの送信状況を確認してみましょう。