エクスポートされたログの BigQuery スキーマ

このページでは、Cloud Logging から BigQuery にログエントリをエクスポートするときに適用される形式とルールについて説明します。

Logging は、読み込みジョブを使用する代わりに、ログデータを BigQuery に一度に 1 レコードずつストリーミングします。このアプローチにより、読み込みジョブの実行に遅延を発生させることなく、BigQuery でデータのクエリを実行できます。詳細については、BigQuery へのデータのストリーミングをご覧ください。

エクスポートされたログに対する BigQuery テーブルスキーマは、LogEntry 型の構造とログのペイロードの内容に基づいています。また、Cloud Logging では、監査ログの BigQuery スキーマフィールド名を短縮するための特別なルールが適用されます。テーブルスキーマを確認するには、BigQuery ウェブ UI でエクスポートされたログエントリのテーブルを選択します。

フィールド命名規則

ログエントリフィールドに適用される命名規則がいくつかあります。

LogEntry 型の一部であるログエントリフィールドの場合、対応する BigQuery フィールド名はログエントリフィールドとまったく同じです。
ユーザー指定のフィールドの場合、大文字小文字は小文字に正規化されますが、それ以外は名前は保持されます。
- 構造化ペイロードのフィールドの場合、@type 指定子が存在しない限り、大文字小文字は小文字に正規化されますが、それ以外は名前は保持されます。
  
  @type 指定子が存在する構造化ペイロードについては、@type を含むペイロードフィールドをご覧ください。

次の例は、これらの命名規則がどのように適用されるかを示しています。

ログエントリフィールド	LogEntry 型マッピング	BigQuery フィールド名
`insertId`	`insertId`	`insertId`
`textPayload`	`textPayload`	`textPayload`
`httpRequest.status`	`httpRequest.status`	`httpRequest.status`
`httpRequest.requestMethod.GET`	`httpRequest.requestMethod.[ABC]`	`httpRequest.requestMethod.get`
`resource.labels.moduleid`	`resource.labels.[ABC]`	`resource.labels.moduleid`
`jsonPayload.MESSAGE`	`jsonPayload.[ABC]`	`jsonPayload.message`
`jsonPayload.myField.mySubfield`	`jsonPayload.[ABC].[XYZ]`	`jsonPayload.myfield.mysubfield`

構造化ペイロードフィールドを BigQuery フィールド名にマッピングする場合、構造化フィールドに @type 指定子が含まれているとさらに複雑になります。これについては次のセクションで説明します。

@type を含むペイロードフィールド

このセクションでは、ログエントリのペイロードに型指定子（@type フィールド）が含まれている特別な BigQuery スキーマフィールド名について説明します。これには、エクスポートされて BigQuery で保持されている監査ログエントリも含まれます。また、このセクションでは、監査ログエントリの protoPayload フィールドが BigQuery スキーマフィールド protopayload_auditlog にマッピングされる理由についても説明します。

スキーマの命名規則

ログエントリのペイロードには構造化データを含めることができ、その構造化データにはネストされた構造化フィールドを含めることができます。すべての構造化フィールドには、オプションの型指定子を次の形式で含めることができます。

@type: type.googleapis.com/[TYPE]

型指定子を持つ構造化フィールドには、通例、フィールド名に[TYPE]が追加された BigQuery フィールド名が付けられます。[TYPE]の値には任意の文字列を指定できます。

たとえば、次の表は、最上位の構造化ペイロードフィールドの BigQuery フィールド名へのマッピングを示しています。

ペイロード	ペイロード @type	ペイロードフィールド	BigQuery フィールド名
`jsonPayload`	（なし）	`statusCode`	`jsonPayload.statusCode`
`jsonPayload`	`type.googleapis.com/abc.Xyz`	`statusCode`	`jsonPayload_abc_xyz.statuscode`
`protoPayload`	（なし）	`statusCode`	`protoPayload.statuscode`
`protoPayload`	`type.googleapis.com/abc.Xyz`	`statusCode`	`protopayload_abc_xyz.statuscode`

jsonPayload または protoPayload に他の構造化フィールドが含まれている場合、これらの内部フィールドは次のようにマップされます。

ネストされた構造化フィールドに @type 指定子が含まれていない場合、小文字に正規化されることを除き、その BigQuery フィールド名は元のフィールド名と同じになります。
ネストされた構造化フィールドに @type 指定子が含まれている場合、その BigQuery フィールド名は、フィールド名に [TYPE]（再表記）が付けられたものになり、小文字に正規化されます。

型指定子を含むフィールドでは、上記のルールにいくつかの例外があります。

App Engine のリクエストログでは、ペイロードに型指定子が含まれる場合でも、BigQuery にエクスポートされたログのペイロード名は protoPayload になります。
Cloud Logging では、監査ログの BigQuery スキーマフィールド名を短縮するための特別なルールが適用されます。これについては、下記のエクスポートされた監査ログスキーマのフィールドセクションで説明します。

例

この例は、構造化ペイロードフィールドが BigQuery にエクスポートされたときに、どのような名前になり、どのように使用されるかを示しています。

ログエントリのペイロードが次のように構成されているとします。

jsonPayload: {
  name_a: {
    sub_a: "A value"
  }
  name_b: {
    @type: "type.googleapis.com/google.cloud.v1.SubType"
    sub_b: 22
  }
}

BigQuery フィールドへのマッピングは次のとおりです。

フィールド jsonPayload と name_a は構造化されていますが、@type 指定子はありません。BigQuery での名前はそれぞれ jsonPayload と name_a になります。
フィールド sub_a と sub_b は構造化されていないため、BigQuery での名前はそれぞれ sub_a と sub_b になります。
フィールド name_b には @type 指定子があり、[TYPE] は google.cloud.v1.SubType です。したがって、BigQuery での名前は name_b_google_cloud_v1_subtype になります。

つまり、ログエントリのペイロードに対して次の 5 つの BigQuery 名が定義されます。

jsonPayload
jsonPayload.name_a
jsonPayload.name_a.sub_a
jsonPayload.name_b_google_cloud_v1_subtype
jsonPayload.name_b_google_cloud_v1_subtype.sub_b

エクスポートされた監査ログのフィールド

BigQuery にエクスポートされた監査ログを扱わない場合は、このセクションをスキップできます。

監査ログのペイロードフィールドである protoPayload.request、protoPayload.response、protoPayload.metadata には、@type 型指定子が付与されていますが、JSON データとして扱われます。つまり、それらの BigQuery スキーマ名は、フィールド名に Json が追加され、JSON 形式の文字列データを含む形式になります。

次の表に、これら 2 つの監査ログのペイロードフィールド名を示します。

ログエントリフィールド	BigQuery フィールド名
`protoPayload`	`protopayload_auditlog`
`protopayload.metadata`	`protopayload_auditlog.metadataJson`
`protoPayload.serviceData`	`protopayload_auditlog.servicedata_v1_bigquery` 例: `protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest`
`protoPayload.request`	`protopayload_auditlog.requestJson`
`protoPayload.response`	`protopayload_auditlog.responseJson`

serviceData 命名規則は、BigQuery によって生成され、Cloud Logging から BigQuery にエクスポートされる監査ログに固有です。これらの監査ログエントリには、次のような @type 指定子がある serviceData フィールドが含まれています。type.googleapis.com/google.cloud.bigquery.logging.v1.auditdata

例

BigQuery によって生成された監査ログエントリには、次の名前のフィールドがあります。

protoPayload.serviceData.tableInsertRequest

このログエントリが BigQuery にエクスポートされた場合、tableInsertRequest フィールドはどのように参照されますか。名前を短縮する前、対応するエクスポートされたフィールド名は次のようになります。

protopayload_google_cloud_audit_auditlog.servicedata_google_cloud_bigquery_logging_v1_auditdata.tableInsertRequest

名前の短縮後、同じフィールドが BigQuery テーブルでは次のように参照されます。

protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest

パーティション分割テーブル

このセクションでは、BigQuery へのログのエクスポートのパーティション分割テーブルの概要について説明します。

BigQuery データセットにログをエクスポートすると、Logging はエクスポートされたログエントリを保持するテーブルを作成します。Logging がエクスポートするデータを整理する 2 つのテーブルタイプ（日付別シャーディングテーブルとパーティション分割テーブル）があります。どちらのテーブルタイプも、ログエントリの timestamp フィールドに基づいてログデータを分割します。ただし、テーブルタイプ間には次の 2 つの主な違いがあります。

パフォーマンス: パーティション分割テーブルは、大きいテーブルを小さいパーティションに分割するため、クエリのパフォーマンスを向上させ、クエリの読み込みバイト数を減らすことで BigQuery の費用をより効率的に管理できます。
テーブルの命名法: テーブルタイプでは、次のセクションで説明するように、異なる命名規則が使用されます。

テーブルの構成

エクスポートされたログエントリは、エントリのログ名とタイムスタンプに基づく名前の BigQuery テーブルに格納されます。

次の表は、ログ名とサンプルのタイムスタンプを BigQuery のテーブル名にマップする例を示しています。

ログ名	ログエントリ `timestamp`	BigQuery テーブル名（日付別）	BigQuery テーブル名（パーティション分割）
`syslog`	`2017-05-23T18:19:22.135Z`	`syslog_20170523`	`syslog`
`apache-access`	`2017-01-01T00:00:00.000Z`	`apache_access_20170101`	`apache_access`
`compute.googleapis.com/activity_log`	`2017-12-31T23:59:59.999Z`	`compute_googleapis_com_activity_log_20171231`	`compute_googleapis_com_activity_log`

パーティション分割テーブルの作成

シンクを作成して BigQuery にログをエクスポートする場合は、日付別シャーディングテーブルまたはパーティション分割テーブルを使用できます。デフォルトの選択は、日付別シャーディングテーブルです。

Google Cloud Console を使用する手順については、ログビューアを使用してエクスポートをご覧ください。

コマンドラインインターフェースの Cloud SDK を使用する手順については、gcloud alpha logging sinks create をご覧ください。

スキーマの不一致

宛先 BigQuery テーブルのスキーマは、最初にエクスポートされるログエントリによって決定されます。ログエントリは、ログエントリのフィールドとその型に基づいた列を持つテーブルを生成します。後続のログエントリに新しいフィールドが表示されると、テーブルスキーマが更新されます。ただし、既存のフィールドの値タイプが変更された場合、スキーマに一致しない新しいログエントリは破棄されます。

たとえば、最初のエクスポートに jsonPayload.user_id が string のログエントリが含まれている場合、そのログエントリは、そのフィールドの文字列型を持つテーブルを生成します。jsonPayload.user_id を array としてロギングを開始した場合、それらのログエントリはテーブルに挿入されず、失われます。

Logging は、エクスポートを含む Google Cloud プロジェクトのこのデータ損失を次の方法で通知します。

プロジェクトオーナーにメールを送信します。詳細には、Google Cloud のプロジェクト ID、シンク名、エクスポート先が含まれます。
Google Cloud Console の [アクティビティ] ページにエラー Stackdriver Config error が表示されます。詳細には、シンク名とエクスポート先、エラーの原因となったログエントリの例へのリンクが含まれます。
システムログベースの指標 exports/error_count は、エラーのためにエクスポートされなかったログエントリの合計数を示します。

後続のログエントリの問題を修正して、それ以上データが失われないようにするには、現在のスキーマに一致するようにフィールド型を修正します。また、テーブルの名前を変更するか、シンクのパラメータを変更して、Logging で別のデータセットのテーブルを再作成することもできます。手順については、シンクを更新するをご覧ください。

ログの表示

BigQuery ウェブ UI を使用してログを表示するには、エクスポートされたログエントリがあるテーブルを選択します。