このページでは、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 は次のルールを使用して、現在のメッセージ バッチ内のログエントリが書き込まれるテーブルを決定します。
フィールド タイプの変更が発生すると、スキーマの不一致を引き起こしたログエントリのみがエラーテーブルに書き込まれます。スキーマの不一致が発生しない現在のメッセージのログエントリは、元の宛先テーブルに書き込まれます。
列上限を超えると、現在のメッセージのバッチ内のすべてのログエントリがエラーテーブルに書き込まれます。
エラーテーブルには、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 で表示する手順については、シンクのエクスポート先のログを表示するをご覧ください。