OTLP ログレコードからログエントリへのマッピング

このドキュメントでは、OTLP ログレコードが Telemetry API を使用して Google Cloud に送信されるときに、Google Cloud Observability が OTLP ログレコードから LogEntry のフィールドを決定する方法について説明します。

OTLP 形式のログデータの一般的な構造

Telemetry API を使用してログデータを Google Cloud に送信する場合、このデータは OTLP と一貫性のある形式である必要があります。このデータの一般的な構造は次のとおりです。

"resourceLogs": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeLogs": [
        {
          "logRecords": [...]
        }
      ]
    }
]

OpenTelemetry は個々のログをバッチ処理します。各ログは logRecord 構造で表され、ログのソースに関する情報は resource 構造で表されます。

Google Cloud Observability が resourceLogs オブジェクトを受け取ると、logRecord ごとに 1 つの LogEntry が作成されます。個々のログのコレクションでソース情報をバッチ処理する OTLP とは異なり、各 LogEntry 構造には、ログのソースとログ自体に関する情報が含まれています。

OTLP 形式のログデータの構造の詳細については、OpenTelemetry の logs.proto をご覧ください。

LogEntry フィールドの設定方法

Google Cloud Observability は、次のルールを使用して LogEntry フィールドの値を決定します。

LogEntry フィールド
（HTTP リファレンスからの名前）		 システムがフィールド値を決定する方法
logName

システムは、次の優先順位付きの OpenTelemetry ログレコード属性リストを使用して、ログ名を決定します。

  • gcp.log_name
  • log_name
  • event_name

ログ名は URL で使用可能な文字にするか、取り込み時に URL エンコードする必要があります。
resource システムは、resource フィールドで設定された情報を使用するか、リソースを推測します。詳細については、OTLP 属性とリソースタイプのマッピングをご覧ください。
timestamp

システムは、次の優先順位の OpenTelemetry ログレコード フィールドのリストを使用して timestamp を決定します。

  • ゼロ以外の場合 time_unix_nano。
  • ゼロ以外の場合 observed_time_unix_nano。
  • ログエントリが取り込まれた時刻。

データを保存するログバケットの保持期間によって、取り込むことができる最も古いタイムスタンプが決まります。詳細については、Cloud Logging の割り当てをご覧ください。
receiveTimestamp LogEntry が取り込まれた時刻に設定します。
severity システムは、ログレコードの OpenTelemetry の重大度を Cloud Logging の重大度にマッピングします。詳細については、重大度フィールドをご覧ください。
httpRequest

システムは、ログレコードの gcp.http_request 属性を同等の LogEntry フィールドにマッピングします。詳細については、HttpRequest フィールドをご覧ください。

FIXME。このフィールドにマッピングされる他のフィールドがあります。
labels システムは、ログレコードの属性値を使用してこのフィールドを設定します。詳細については、ラベル フィールドをご覧ください。
trace システムは、このフィールドをログレコードの traceId フィールドの値に設定します。値は有効な 32 文字の 16 進文字列にする必要があります。そうでない場合、エントリは拒否されます。
spanId システムは、このフィールドをログレコードの spanId フィールドの値に設定します。値は有効な 16 文字の 16 進文字列にする必要があります。そうでない場合、エントリは拒否されます。
traceSampled 未設定。
sourceLocation このフィールドには、ログレコードの Code 属性の値が設定されます。詳細については、SourceLocation フィールドをご覧ください。
split 未設定。
apphub
apphubDestination
apphubSource
 未設定。
otel LogEntry に同等のフィールドがない OTLP ログデータのフィールドの場合、システムはデータ型を変換し、変換されたデータを otel フィールドに追加します。詳細については、Otel フィールドをご覧ください。
ペイロード システムは、ログレコードの本文を適切なペイロード タイプに変換してペイロードを設定します。詳細については、ペイロード フィールドをご覧ください。

HttpRequest フィールド

Google Cloud Observability は、HTTP リクエストに適用される OTLP 属性を LogEntry フィールドにマッピングします。以降のセクションでは、システムがフラット属性とネストされた属性をマッピングする方法について説明します。

フラット属性

次の表に、Google Cloud Observability が HTTP リクエストに適用されるフラット属性を LogEntry フィールドにマッピングする方法を示します。たとえば、属性 http.request.method: "GET", の値がログエントリの httpRequest.requestMethod フィールドの値として設定されます。

OpenTelemetry
LogRecord.attribute
Key-Value ペア。		 次の
LogEntry フィールドに保存される値
（HTTP リファレンスの名前）		 承認済みのタイプ
http.request.method httpRequest.requestMethod 文字列
url.full
http.url 		httpRequest.requestUrl 文字列
http.request.body.size httpRequest.requestSize string、int
http.response.status_code httpRequest.status 文字列、整数
http.response.body.size httpRequest.responseSize string、int
user_agent.original
http.user_agent 		httpRequest.userAgent 文字列
client.address remoteIp 文字列
server.address serverIp 文字列
referrer httpRequest.referer 文字列
latency httpRequest.latency string、int
cacheLookup httpRequest.cacheLookup bool
cacheHit httpRequest.cacheHit bool
cacheValidatedWithOriginServer httpRequest.cacheValidatedWithOriginServer bool
cacheFillBytes httpRequest.cacheFillBytes string、int
network.protocol.version
protocol 		httpRequest.protocol 文字列

ネストされた属性

このセクションでは、Google Cloud Observability が HTTP リクエストに適用されるネストされた OTLP 属性を LogEntry のフィールドにマッピングする方法について説明します。次の例は、2 つの属性を含むログレコードを示しています。各属性には、少なくとも 1 つの他の属性が含まれています。

log_record {
  attributes: {
    gcp.http_request {
      "requestMethod": "GET",
      "requestUrl": "some-URL",
    }
    http_request {
      "requestMethod": "GET",
    }
  }
}

テーブルでは、ネストされた属性は中かっこで囲んで示されています。たとえば、gcp.http_request {requestMethod} は、属性 gcp.http_request に属性 requestMethod が含まれていることを意味します。最も内側の属性の値が、ログエントリ フィールドの値に割り当てられます。

OpenTelemetry
LogRecord.attribute
Key-Value ペア。		 次の
LogEntry フィールドに保存される値
（HTTP リファレンスの名前）		 承認済みのタイプ
gcp.http_request {requestMethod}
http_request {requestMethod} 		httpRequest.requestMethod 文字列
gcp.http_request {requestUrl}
http_request {requestUrl} 		httpRequest.requestUrl 文字列
gcp.http_request {requestSize}
http_request {requestSize} 		httpRequest.requestSize string、int
gcp.http_request {status}
http_request {status} 		httpRequest.status 文字列、整数
gcp.http_request {responseSize}
http_request {responseSize} 		httpRequest.responseSize string、int
gcp.http_request {userAgent}
http_request {userAgent} 		httpRequest.userAgent 文字列
gcp.http_request {remoteIp}
http_request {remoteIp} 		httpRequest.remoteIp 文字列
gcp.http_request {serverIp}
http_request {serverIp} 		httpRequest.serverIp 文字列
gcp.http_request {referer}
http_request {referrer} 		httpRequest.referer 文字列
gcp.http_request {latency}
http_request {latency} 		httpRequest.latency string、int
gcp.http_request {cacheLookup}
http_request {cacheLookup} 		httpRequest.cacheLookup bool
gcp.http_request {cacheHit}
http_request {cacheHit} 		httpRequest.cacheHit bool
gcp.http_request {
cacheValidatedWithOriginServer}
http_request {
cacheValidatedWithOriginServer} 		httpRequest.cacheValidatedWithOriginServer bool
gcp.http_request {cacheFillBytes}
http_request {cacheFillBytes} 		httpRequest.cacheFillBytes string、int
gcp.http_request {protocol}
http_request {protocol} 		httpRequest.protocol 文字列

ラベル フィールド

ログエントリに適用するラベルを決定するために、システムは次の処理を行います。

  1. 特定の LogEntry フィールドにマッピングされた属性を OTLP ログレコードから削除します。

    たとえば、ログレコードに次の属性が付加されているとします。

    attributes: {
    "log_array_attr: ["value1", "value2"],
    "log_json_attr": {"json_key": "json_value"}
    "log-string-attr": "string",
    "code.file.path": "my-file.cc",
    "code.function.name: "my-func",
    "code.line.number": 123,
    "gcp.http_request": {
        "requestMethod": "GET",
        "requestUrl": "my-URL",
  },
}

    特定の LogEntry フィールドにマッピングされているフィールドを削除すると、次のフィールドが残ります。

    attributes: {
    "log_array_attr: ["value1", "value2"],
    "log_json_attr": {"json_key": "json_value"}
    "log-string-attr": "string",
}

  2. 属性に配列または JSON 要素が含まれている場合、システムは値を文字列に変換します。

    たとえば、次の例は、LogEntry が以前の属性をどのように表すかを示しています。

    labels: {
    "log_array_attr": "[\"value1\",\"value2\"]",
    "log_json_attr": "{\"json_key\":\"json_value\"}",
    "log-string-attr": "string",
}

    属性の最大ネスト深度は 5 です。ネストが深いコンテンツは切り捨てられます。

Otel フィールド

LogEntry に同等のフィールドがない OTLP ログデータのフィールドの場合、システムはデータ型を変換し、変換されたデータを otel フィールドに追加します。たとえば、otel フィールドには resource、scope、entity フィールドの属性が格納されます。

システムは、次のルールを使用して OpenTelemetry データ型を protobuf Value 型に変換します。

OpenTelemetry のタイプ protobuf 型
string string
boolean bool
integer double
float double
Array ListValues
KeyValueList Struct

倍精度エラーを回避するには、整数を文字列として渡します。

ペイロード フィールド

OTLP の logRecord.body フィールドのデータ型によって、LogEntry ペイロードの構造が決まります。

  • string: システムは文字列を LogEntry.textPayload フィールドにコピーします。

  • Array: システムは、改行を保持しながら配列要素の文字列を作成します。次に、文字列を LogEntry.textPayload フィールドにコピーします。

  • KeyValueList: システムはこれらのペアを JSON に変換し、次の制限事項に従って LogEntry.jsonPayload フィールドに入力します。

    • OTLP レコードに重複する属性キーが含まれている場合、システムは最初のキーを保持し、重複するキーを持つ属性を破棄します。
    • JSON ペアのネストの深さが 5 より大きい場合、システムはコンテンツを深さ 5 まで切り捨てます。

重大度フィールド

このセクションでは、Google Cloud Observability が OpenTelemetry の重大度フィールドを Cloud Logging の重大度レベルにマッピングする方法について説明します。OpenTelemetry は、重大度番号と重大度テキストを定義します。logs.proto は重大度番号を定義します。

Google Cloud Observability は、OpenTelemetry の重大度番号が設定されている場合は、その番号から Logging の重大度を決定します。それ以外の場合は、重大度のテキストを使用します。どちらも設定されていない場合、ロギングの重大度は DEFAULT に設定されます。

OpenTelemetry の重大度番号
列挙型（値）		 OpenTelemetry の重大度テキスト
（テストでは大文字と小文字は区別されません）		 Cloud Logging の重大度
列挙型（値）
SEVERITY_NUMBER_UNSPECIFIED（0） 「default」
設定なし		 DEFAULT（0）
SEVERITY_NUMBER_TRACE （1）
SEVERITY_NUMBER_TRACE2 （2）
SEVERITY_NUMBER_TRACE3 （3）
SEVERITY_NUMBER_TRACE4 （4）		 "trace"
"trace2"
"trace3"
"trace4"		 DEBUG（100）
SEVERITY_NUMBER_DEBUG （5）
SEVERITY_NUMBER_DEBUG2 （6）
SEVERITY_NUMBER_DEBUG3 （7）
SEVERITY_NUMBER_DEBUG4 （8）		 「debug」
「debug2」
「debug3」
「debug4」		 DEBUG（100）
SEVERITY_NUMBER_INFO （9）
SEVERITY_NUMBER_INFO2（10）		 "info"
"info2"		 INFO（200）
SEVERITY_NUMBER_INFO3（11）
SEVERITY_NUMBER_INFO4（12）		 "notice"
"info3"
"info4"		 NOTICE（300）
SEVERITY_NUMBER_WARN （13）
SEVERITY_NUMBER_WARN2 （14）
SEVERITY_NUMBER_WARN3 （15）
SEVERITY_NUMBER_WARN4 （16）		 「warning」
「warn」
「warn2」
「warn3」
「warn4」		 WARNING（400）
SEVERITY_NUMBER_ERROR （17）
SEVERITY_NUMBER_ERROR2（18）
SEVERITY_NUMBER_ERROR3（19）
SEVERITY_NUMBER_ERROR4（20）		 "error"
"error2"
"error3"
"error4"		 ERROR（500）
SEVERITY_NUMBER_FATAL （21）
SEVERITY_NUMBER_FATAL2（22）		 "critical"
"fatal"
"fatal2"		 CRITICAL（600）
SEVERITY_NUMBER_FATAL3（23） "alert"
"fatal3"		 ALERT（700）
SEVERITY_NUMBER_FATAL4（24） "emergency"
"fatal4"		 EMERGENCY（800）

SourceLocation フィールド

Google Cloud Observability は、次の OTLP コードを LogEntry フィールドに直接マッピングします。このマッピングが可能なのは、これらの OpenTelemetry 属性が Cloud Logging のコンセプトと意味的に同じであるためです。

OpenTelemetry
LogRecord.attribute
Key-Value ペア。		 次の
LogEntry フィールドに保存される値
（HTTP リファレンスの名前）		 承認済みのタイプ
code.file.path: Value sourceLocation.file 文字列
code.function.name: Value sourceLocation.function 文字列
code.function.number: Value sourceLocation.line string、int

制限事項

このセクションでは、制限について説明します。また、Google Cloud Observability が特定の種類のデータを処理する方法についても説明します。

上限

説明 値 メモ
OTLP リクエストあたりのログの最大数 8192 OTLP resourceLogs 構造の logRecords の最大数を指します。上限。
各リクエストの最大サイズ 5 MiB 上限。
OTLP ログレコードから作成される LogEntry
の最大サイズ		 256 KiB Cloud Logging は、必要に応じて OTLP ログレコードからデータを切り捨てたり、破棄したりします。上限。
属性キーの最大長 512 B OTLP ログレコードが LogEntry に変換されると、サイズ超過のラベルキーは切り捨てられます。上限。
属性値の最大長 64 KiB OTLP ログレコードが LogEntry に変換される際のサイズ超過のラベル値。上限。
属性のネストの最大深度 5 この上限を超える属性は、OTLP ログレコードが LogEntry に変換されるときに切り捨てられます。
1 分あたりのログ取り込みバイト数の最大値

次の地域では 2.4 GB: asia-east1, asia-northeast1, asia-southeast1, asia-south1, europe-west1, europe-west2, europe-west3, europe-west4, us-central1, us-east4, us-west1。

その他のすべてのリージョンでは 300 MB。

 割り当て。

動作

  • OpenTelemetry の重大度番号と重大度テキストの両方が設定されている場合、システムは重大度番号を使用して Cloud Logging の重大度レベルを決定します。OTLP レコードに重大度情報が含まれていない場合、Cloud Logging の重大度レベルは DEFAULT に設定されます。

  • OTLP レコードに重複する属性キーが含まれている場合、システムは最初のキーを保持し、重複するキーを持つ属性を破棄します。

  • システムは、ログレコードに付加された属性を文字列に変換します。例については、ラベル フィールドをご覧ください。

  • ログ名は URL セーフであるか、取り込み時に URL エンコードされている必要があります。ログ名の設定方法については、LogEntry フィールドの設定方法をご覧ください。