ログ用の 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 を使用する手順については、シンクを構成して管理するをご覧ください。

gcloud コマンドライン ツールの使用手順については、gcloud logging sinks create をご覧ください。

スキーマの不一致

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

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

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

    たとえば、最初のログエントリの jsonPayload.user_id フィールドが string の場合、そのログエントリは、そのフィールドの文字列型を持つテーブルを生成します。後になって jsonPayload.user_id を array としてロギングを開始した場合、スキーマの不一致が発生します。

  • ログエントリに新しいフィールドが追加されるため、宛先テーブルの列数が BigQuery の列上限を超えます。列上限の詳細については、BigQuery の割り当てと上限をご覧ください。

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

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

  • フィールド タイプの変更が発生すると、スキーマの不一致の原因となったログエントリのみがエラーテーブルに書き込まれます。スキーマの不一致が発生しない現在のメッセージのログエントリは、元の宛先テーブルに書き込まれます。

  • 列上限を超えると、現在のメッセージのバッチ内のすべてのログエントリがエラーテーブルに書き込まれます。

エラーテーブルには、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 で表示する手順については、シンクのエクスポート先のログを表示するをご覧ください。