ログ用の BigQuery スキーマ

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

概要

シンクを使用して、Cloud Logging から BigQuery にログエントリをルーティングできます。シンクを作成するときは、宛先として BigQuery データセットを定義します。Logging は、シンクのルールに一致するログエントリを、その BigQuery データセット内に作成されたパーティション分割テーブルに送信します。

Cloud Logging から受信するデータの BigQuery テーブルスキーマは、LogEntry タイプの構造とログエントリのペイロードの内容に基づいています。また、Cloud Logging では、監査ログと特定の構造化ペイロードフィールドの BigQuery スキーマフィールド名を短縮するルールも適用されます。

Logging シンクは、ロギングデータを小さなバッチで BigQuery にストリーミングし、読み込みジョブを実行せずにデータをクエリできるようにします。詳細については、BigQuery へのデータのストリーミングをご覧ください。料金については、BigQuery の料金: データ取り込みの料金のストリーミング挿入セクションをご覧ください。

フィールド命名規則

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

ログエントリフィールドの名前は 128 文字以下にする必要があります。
ログエントリのフィールド名は英数字のみで構成できます。サポートされていない文字はフィールド名から削除され、アンダースコアに置き換えられます。たとえば、jsonPayload.foo%% は jsonPayload.foo__ に変換されます。

ログエントリのフィールド名は、変換後も英数字で始める必要があります。先頭のアンダースコアはすべて削除されます。
LogEntry 型の一部であるログエントリフィールドの場合、対応する BigQuery フィールド名はログエントリフィールドとまったく同じです。
ユーザー指定のログエントリフィールドの場合、対応する BigQuery フィールド名は小文字に正規化されますが、それ以外は名前は保持されます。
構造化ペイロードのフィールドの場合、@type 指定子が存在しない限り、対応する BigQuery フィールド名は小文字に正規化されますが、それ以外は名前は保持されます。

@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`

`@type` でのペイロードフィールド

このセクションでは、ペイロードに指定子 @type を含むログエントリの特別な BigQuery スキーマフィールド名について説明します。これには、BigQuery にルーティングされる監査ログエントリも含まれます。

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

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

命名規則は、監査ログエントリの protoPayload フィールドが BigQuery スキーマフィールド protopayload_auditlog にマッピングされる理由を説明しています。

`@type` の命名規則

型指定子を含む構造化フィールドには、フィールド名に [TYPE] が付いた BigQuery フィールド名が指定されます。[TYPE] の値は、任意の文字列にできます。

@type の命名規則は、jsonPayload または protoPayload の最上位にのみ適用されます。ネストされたフィールドは無視されます。最上位の構造化ペイロードフィールドを処理する場合、Logging は接頭辞 type.googleapis.com を削除します。

たとえば、次の表は、最上位の構造化ペイロードフィールドの 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`

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

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

例

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

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

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

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

最上位の構造化フィールド jsonPayload には、@type 指定子が含まれています。BigQuery での名前は jsonpayload_v1_customtype です。
ネストされたフィールドは、標準の BigQuery 命名規則として扱われます。ネストされたフィールドには、型指定子ルールが適用されないためです。

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

  jsonpayload_v1_customtype
  jsonpayload_v1_customtype._type
  jsonpayload_v1_customtype.name_b
  jsonpayload_v1_customtype.name_b.sub_b
  jsonpayload_v1_customtype.name_a
  jsonpayload_v1_customtype.name_a.sub_a

監査ログのフィールド

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 フィールドはどのように参照されますか。名前を短縮する前は、BigQuery の対応するフィールド名は次のようになります。

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 テーブルにシャーディングされます。

テーブル名には、ログエントリの UTC タイムスタンプ（ISO 8601 の基本形式である YYYYMMDD を使用）のカレンダー日付が末尾に付加されます。

次の表は、ログ名とサンプルのタイムスタンプを 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 を使用する手順については、シンクを構成して管理するをご覧ください。

Google Cloud CLI の使用方法については、gcloud logging sinks create をご覧ください。

スキーマの不一致

宛先 BigQuery テーブルのスキーマは、BigQuery で最初に受信するログエントリによって決定されます。BigQuery は、最初のログエントリのフィールドとその型に基づいた列を持つテーブルを作成します。

スキーマの不一致が発生するのは、ログエントリが宛先テーブルに書き込まれ、次のいずれかのエラーが発生した場合です。

後のログエントリで、テーブル内の既存のフィールドのフィールドタイプを変更します。

たとえば、最初のログエントリの jsonPayload.user_id フィールドが string の場合、そのログエントリは、そのフィールドの文字列型を持つテーブルを生成します。後になって jsonPayload.user_id を array としてロギングを開始した場合、スキーマの不一致が発生します。
新しいログエントリに、現在のスキーマにないフィールドがあり、そのフィールドを宛先テーブルに挿入すると BigQuery の列の制限を超えます。

宛先テーブルが列の上限を超えなければ、新しいフィールドを受け入れることができます。

BigQuery は、スキーマの不一致を特定すると、対応するデータセット内にテーブルを作成してエラー情報を保存します。テーブルタイプによって、テーブル名が決まります。日付別テーブルの場合、命名形式は export_errors_YYYYMMDD です。パーティション分割テーブルの場合、命名形式は export_errors です。詳しくは、テーブルの構成をご覧ください。

ログエントリをルーティングする場合、Logging はメッセージをバッチとして BigQuery に送信します。BigQuery は次のルールを使用して、現在のメッセージバッチ内のログエントリが書き込まれるテーブルを決定します。

フィールドタイプの変更が発生すると、スキーマの不一致を引き起こしたログエントリのみがエラーテーブルに書き込まれます。スキーマの不一致が発生しない現在のメッセージのログエントリは、元の宛先テーブルに書き込まれます。
列上限を超えると、現在のメッセージのバッチ内のすべてのログエントリがエラーテーブルに書き込まれます。

注: BigQuery は、テーブルへのネストされたデータの読み込みをサポートしています。ただし、Logging からデータを読み込む場合、列のネストの深さは最大 13 レベルに制限されます。

エラーテーブルには、LogEntry のデータと不一致に関する情報が含まれています。

エラーテーブルに書き込まれる LogEntry フィールド。
- logName
- timestamp
- receiveTimestamp
- severity
- insertId
- trace
- resource.type
エラーテーブルに書き込まれるスキーマ不一致情報。
- ログシンクの完全なリソースパス
- BigQuery から返される完全なエラーメッセージ
- 完全なログエントリ。ただし、ログエントリは JSON から文字列に変換されます

Logging は、次の方法でルーティングシンクを含む Cloud プロジェクトにスキーマの不一致を通知します。

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

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

ログを表示する

ルーティングされたログを BigQuery で表示する手順については、シンクのエクスポート先のログを表示するをご覧ください。