Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

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

Cloud Logging 用の Google Cloud エクスポータは、OTLP 形式のログデータを LogEntry オブジェクトに変換します。次に、Cloud Logging API を使用して、このデータを Google Cloud プロジェクトに送信します。ただし、Google Cloud Observability とエクスポータがログエントリの作成に使用するデフォルトのルールは異なります。詳細については、エクスポータマッピングを使用するように Google Cloud Observability を構成するをご覧ください。

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`	システムは、OTLP `LogRecord` の `event_name` フィールドの値を使用します。そのフィールドが存在しないか、設定されていない場合、システムは次の優先順位付きの OpenTelemetry ログレコード属性リストを使用してログ名を決定します。 `log.name` `gcp.log.name` `log_name` `gcp.log_name` `logging.googleapis.com/logName` `service.name` `gcp.service.name` `service_name` `gcp.service_name` `event.name` `gcp.event.name` `event_name` `gcp.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`	システムは、ログレコードの `flags` フィールドの下位ビットに基づいてこのフィールドを設定します。下位ビットが `1` と等しい場合、このフィールドは `true` に設定されます。それ以外の場合は、設定されません。
`sourceLocation`	システムは、このフィールドをログレコードの Code 属性の値に設定します。詳細については、SourceLocation フィールドをご覧ください。
`split`	未設定。
`apphub` `apphubDestination` `apphubSource`	未設定。
`otel`	`LogEntry` に同等のフィールドがない OTLP ログデータのフィールドの場合、システムはデータ型を変換し、変換されたデータを `otel` フィールドに追加します。詳細については、Otel フィールドをご覧ください。
`operation`	システムは、ログレコードの `gcp.operation` 属性を同等の `LogEntry` フィールドにマッピングします。詳細については、オペレーションフィールドをご覧ください。
ペイロード	システムは、ログレコードの本文を適切なペイロードタイプに変換してペイロードを設定します。詳細については、ペイロードフィールドをご覧ください。

HttpRequest フィールド

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

フラット属性

次の表に、HTTP リクエストに適用されるフラット属性を Google Cloud Observability が 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`	string、int
`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 のフィールドにマッピングする方法について説明します。次の例は、それぞれに 1 つ以上の属性が含まれる 2 つの属性を含むログレコードを示しています。

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`	string、int
`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`	文字列

ラベルフィールド

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

特定の 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",
}

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

たとえば、次の例は、LogEntry が以前の属性をどのように表すかを示しています。
```
labels: {
    "log_array_attr": "[\"value1\",\"value2\"]",
    "log_json_attr": "{\"json_key\":\"json_value\"}",
    "log-string-attr": "string",
}
```
属性の最大ネスト深度は 5 です。ネストが深いコンテンツは切り捨てられます。

オペレーションフィールド

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

gcp.operation 属性には Key-Value 型を含める必要があります。フラット化された属性名はサポートされていません。次の例は、gcp.operation 属性に 4 つの Key-Value ペアを含むログレコードを示しています。

log_record {
  attributes: {
    gcp.operation {
      "id": "abc123",
      "producer": "my_producer",
      "first": "true",
      "last": "false",
    }
  }
}

次の表に、Google Cloud Observability が gcp.operation を LogEntry にマッピングする方法を示します。

OpenTelemetry `LogRecord.attribute.operation` Key-Value ペア。	次の `LogEntry` オペレーションフィールドに格納される値	承認済みのタイプ
`id`	`id`	文字列
`producer`	`httpRequest.requestUrl`	文字列
`first`	`first`	bool
`last`	`last`	bool

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 の重大度番号からロギングの重大度を決定します。設定されていない場合は、重大度テキストを使用します。どちらも設定されていない場合、ロギングの重大度は 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 フィールドの設定方法をご覧ください。

エクスポータマッピングを使用するように Google Cloud Observability を構成する

Google Cloud Observability と Cloud Logging 用の Google Cloud エクスポータは、異なるルールを使用して OTLP 形式のログデータから LogEntry オブジェクトを構築します。たとえば、Google Cloud Observability は otel フィールドに入力しますが、エクスポータは入力しません。

Google Cloud Observability でエクスポータと同じマッピングルールを使用する場合は、OTLP ログレコードを Telemetry API に送信するアプリケーションに次の変更を加えます。

リクエストに含まれるリソースに gcp.use_legacy_mapping 属性を追加します。詳細については、属性の追加または削除をご覧ください。

この属性を設定すると、次のようになります。
1. otel フィールドが入力されていません。
2. gcp で始まる属性は、次の例外を除き破棄されます。
  - gcp.log.name
  - gcp.insert_id
  前の 2 つの属性は LogEntry フィールドにマッピングされます。
以前のマッピングルールにより、Google Cloud Observability は一部のコンテンツを破棄しますが、LogEntry オブジェクトのサイズは小さくなります。
次のログラベルを設定するプロセッサを OTLP HTTP コレクタに追加します。
- instrumentation_scope: instrumentation_scope.name に設定します。
- instrumentation_version: instrumentation_scope.version に設定します。
- service.name: resource.attributes["service.name"] に設定します。
- service.namespace: resource.attributes["service.namespace"] に設定します。
- service.instance.id: resource.attributes["service.instance.id"] に設定します。
例については、OTLP エクスポータに移行する: プロセッサをご覧ください。