このページでは、Cloud Logging から BigQuery にログエントリをエクスポートするときに適用される形式とルールについて説明します。
Logging では、読み込みジョブを使用する代わりに、ロギングデータが一度に 1 レコードとして BigQuery にストリーミングされます。この手法を使用すると、読み込みジョブの実行が遅延することなく、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 テーブルにシャーディングされます。
テーブル名には、ログエントリの 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 を使用する手順については、ログ エクスプローラによるエクスポートをご覧ください。
コマンドライン インターフェースの Cloud SDK を使用する手順については、gcloud 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 を使用してログを表示するには、エクスポートされたログエントリがあるテーブルを選択します。