v1.logs の概要

このドキュメントでは、Telemetry（OTLP）API を使用してプロジェクトに送信されるログデータが Cloud Logging 構造にマッピングされる方法について説明します。 Google Cloud この API は、OpenTelemetry OTLP プロトコルを実装しています。`otlphttp` エクスポータと OpenTelemetry コレクタを使用してアプリケーションを計測する場合、または OpenTelemetry SDK を使用する場合は、この API にデータを送信できます。

OpenTelemetry は、テレメトリーの取り込みと可視化をサポートする Google Cloud エンジニアが常駐する、 Google Cloud-がサポートするオープンソースプロジェクトです。

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

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

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

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

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

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

OTLP 形式のログデータの処理方法

OTLP resourceLogs 構造を Telemetry API に送信すると、Google Cloud Observability は次のアクションを実行します。

logRecord ごとに、LogEntry が作成されます。

次のドキュメントでは、システムが OTLP ログデータから LogEntry を入力する方法について説明します。
- OTLP ログレコードからログエントリへのマッピング。
- OTLP 属性から Cloud Logging リソースタイプへのマッピング。
各 LogEntry には対応する Cloud Logging リソースタイプに関する情報が含まれているため、各 LogEntry は対応する OTLP logRecord よりも大きくなる可能性があります。

OTLP resourceLogs 構造から一連の LogEntry 構造への変換は、不可逆を伴う可能性があります。つまり、LogEntry 構造から元の resource フィールドと logRecord フィールドに変換できない場合があります。
LogEntry は、プロジェクト階層内の集約シンクとプロジェクト内のシンクによって、Cloud Logging API を使用してログエントリがプロジェクトに送信された場合とまったく同じ方法で、に転送されます。

ベストプラクティス

トレースデータを Google Cloud プロジェクトに送信するようにアプリケーションを計測する場合は、OTLP 形式のデータをコレクタに書き込むエクスポータを使用して、トレースデータを Telemetry API に送信することをおすすめします。コレクタでは、ルート URL のみ指定します。

exporters:
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com

OpenTelemetry はデータ型を検出し、必要に応じて /v1/traces、/v1/metrics、または /v1/logs を自動的に追加します。詳細については、 OTLP/HTTP リクエストをご覧ください。

トレースデータまたは指標データを Telemetry API にエクスポートする例については、次のドキュメントをご覧ください。

コレクタを使用できない場合は、プロセス内 OTLP エクスポータを含む OpenTelemetry ライブラリを使用して、テレメトリーを Telemetry API に送信できます。トレースデータを直接エクスポートする方法については、 Cloud Trace エクスポータから OTLP エンドポイントへの移行をご覧ください。

認証

プロジェクトにデータを送信するために必要な認証情報を使用して、エクスポータを構成する必要があります。 Google Cloud たとえば、コレクタを使用する場合は、通常、googleclientauth 拡張機能を使用して Google 認証情報で認証します。

トレースデータの直接エクスポートを使用する場合の認証の例については、認証を構成するをご覧ください。この例では、アプリケーションのデフォルト認証情報（ADC）を使用してエクスポータを構成し、言語固有の Google Auth ライブラリをアプリケーションに追加する方法を示します。 Google Cloud

Cloud Logging とデータ所在地

デフォルトでは、Cloud Logging はプロジェクトで生成されたログエントリをシステム作成のログバケットに転送します。ログバケットは、リージョンリソースです。デフォルトのログシンクを更新して、任意のロケーションにあるカスタムログバケットにログエントリを送信できます。詳細については、ログをリージョン化するをご覧ください。

Cloud Logging には、組織とフォルダ用に構成できる設定が用意されています。これらの設定では、新しいシステム作成のログバケットのロケーション、これらのログバケットで顧客管理の暗号鍵（CMEK）を使用するかどうか、デフォルトのログシンクの構成を指定します。詳細については、組織とフォルダのサポートをご覧ください。

取り込まれたデータを表示する場所

ログデータは、[ログエクスプローラ] ページと [オブザーバビリティ分析] ページで表示できます。詳細については、以下をご覧ください。

制限事項

このセクションでは、制限について説明します。また、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 セーフでない場合は、取り込み時に URL エンコードされます。ログ名の設定方法については、フィールドの設定方法をご覧ください。LogEntry