Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

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

このドキュメントでは、Telemetry API を使用して OTLP ログレコードが 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` フィールドにマッピングします。システムは、これらの属性を構造化属性または JSON 文字列として受け入れます。詳細については、HttpRequest フィールドをご覧ください。
`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 フィールドにマッピングします。以降のセクションでは、システムがフラット属性とネストされた属性をマッピングする方法について説明します。

フラット属性

次の表に、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`	文字列、整数
`http.response.status_code`	`httpRequest.status`	文字列、整数
`http.response.body.size`	`httpRequest.responseSize`	文字列、整数
`user_agent.original` `http.user_agent`	`httpRequest.userAgent`	文字列
`client.address`	`remoteIp`	文字列
`server.address`	`serverIp`	文字列
`referrer`	`httpRequest.referer`	文字列
`latency`	`httpRequest.latency`	文字列、整数
`cacheLookup`	`httpRequest.cacheLookup`	bool
`cacheHit`	`httpRequest.cacheHit`	bool
`cacheValidatedWithOriginServer`	`httpRequest.cacheValidatedWithOriginServer`	bool
`cacheFillBytes`	`httpRequest.cacheFillBytes`	文字列、整数
`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 フィールドの形式は、構造化されたネストされた属性、または構造化された属性の JSON 文字列のいずれかです。

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

表では、ネストされた属性が中かっこで示されています。たとえば、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`	文字列、整数
`gcp.http_request {status}` `http_request {status}`	`httpRequest.status`	文字列、整数
`gcp.http_request {responseSize}` `http_request {responseSize}`	`httpRequest.responseSize`	文字列、整数
`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`	文字列、整数
`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`	文字列、整数
`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 の重大度番号（設定されている場合）から Logging の重大度を決定します。それ以外の場合は、重大度テキストが使用されます。どちらも設定されていない場合、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`	文字列、整数

制限事項

このセクションでは、制限について説明します。また、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` に変換されるときに、サイズ超過のラベル値。制限。
属性のネストの最大深度	20	この上限を超える属性を含むリクエストは、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 エクスポータに移行する: プロセッサをご覧ください。