OTLP ログの取り込みの概要

このドキュメントでは、OTLP 形式のログを Cloud Logging に取り込むために Telemetry（OTLP）API（telemetry.googleapis.com）を使用する方法について説明します。取り込まれたログは、ログエントリとして保存されます。例については、OTLP 形式のログを Telemetry API に書き込むをご覧ください。

SDK を使用するアプリケーションから、または OpenTelemetry Collector を使用して、テレメトリー API にログを送信することもできます。

ログ、指標、トレースの Telemetry API については、Telemetry（OTLP）API リファレンスをご覧ください。

プロトコル サポート

OTLP エンドポイントは、http/protobuf、http/json、grpc などのすべての OTLP プロトコルをサポートしています。OpenTelemetry Collector からエクスポートする場合は、任意のプロトコルを使用できます。ただし、ほとんどの SDK エクスポータでは動的トークンの更新がサポートされていないため、SDK から直接エクスポートする場合は、HTTP エクスポータではなく gRPC OTLP エクスポータのみを使用することをおすすめします。

課金

Telemetry API を使用してログを取り込むと、Cloud Logging のストレージと課金の値が変化することがあります。JSON 形式の OTLP 形式のログ リクエストの一般的な構造は次のとおりです。

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

各 logRecords 配列の各項目は、単一の Cloud Logging ログエントリになります。 Google Cloud プロジェクトのストレージと課金に最も大きな変更が生じるのは、次の両方の条件が満たされている場合です。

  • resource フィールドには、キーと値の必須属性が多数含まれています。これらのリソース属性は、結果の LogEntry でモニタリング対象リソースを特定するために使用されます。

    モニタリング対象リソースは、Cloud Logging のモニタリング対象リソースタイプと、関連付けられたラベルの値で構成されます。モニタリング対象リソースタイプによってはラベルがほとんどないものもあれば、多くのラベルがあるものもあります。OTLP 形式のログの取り込みに必要な属性の詳細については、OTLP 属性とリソースタイプのマッピングをご覧ください。

  • scopeLogs フィールドには、logRecords 配列に大量のアイテムが含まれています。

OTLP 形式のログの取り込みをサポートするため、Cloud Logging の LogEntry 構造には otel という追加のフィールドが含まれています。OTLP と Cloud Logging のデータモデルは完全に一致しないため、otel フィールドには、受信した OTLP リクエストの OTLP リソース、スコープ、エンティティのコピーが含まれます。

たとえば、次のような OTLP resourceLog を Telemetry API に送信すると、結果として得られる各ログエントリには、他のタブに示すように、resource フィールド（モニタリング対象リソース用）と otel フィールドが含まれます。

resourceLog 

{
  "resourceLogs": [
    {
      "resource": {
        "attributes": [
          {
            "key": "gcp.project_id",
            "value": { "stringValue": "PROJECT_ID" }
          },
          {
            "key": "gcp.resource_type",
            "value": { "stringValue": "global" }
          }
        ]
      },
      "scopeLogs": [
        {
          "scope": {
            "name": "my.library",
            "version": "1.0.0",
            "attributes": [
              {
                "key": "my.scope.attribute",
                "value": { "stringValue": "some scope attribute" }
              }
            ]
          },
          "logRecords": [ ... ]
         }
       ]
     }
   ]
}

resource 

  {
    ...
    "resource": {
      "labels": {
        "project_id": "PROJECT_ID"
      },
      "type": "global"
    },
    ...
}

otel 

  {
    ...
    "otel": {
      "resource": {
        "attributes": {
          "gcp.project_id": "PROJECT_ID",
          "gcp.resource_type": "global"
        }
      },
      "scope": {
        "attributes": {
          "my.scope.attribute": "some scope attribute"
        },
        "name": "my.library",
        "version": "1.0.0"
      }
    },
   ...
  }

Cloud Logging には他のリソースをログエントリにリンクする方法がないため、OTLP リソース、スコープ、エンティティに関するすべての情報を各ログエントリにコピーする必要があります。

この複製により、元のリクエストからできるだけ多くの情報が結果のログエントリに保持されます。ただし、重複は、otel フィールドが、ログエントリの monitored-resource（resource）フィールドでも使用されるリソース情報を繰り返すことも意味します。ログエントリの resource フィールドと、otel フィールドで重複しているリソース情報の両方が課金対象となります。

OTLP リクエストに多数のログレコードを含める場合、OTLP 情報は、結果として得られる各ログエントリの resource フィールドと otel フィールドの両方にコピーする必要があります。リクエストに多数の OTLP logRecords を含めると、ログエントリ内の課金対象の resource フィールドの数は、リクエストあたりの resource あたりの OTLP logRecords の数に比例して増加します。

保存される追加情報を最小限に抑えるため、リクエストごとに 1 つの logRecord アイテムを送信することをおすすめします。

制限と割り当て

ロギングに Telemetry API を使用する場合の上限と割り当てについては、ログの取り込みの上限と割り当てをご覧ください。

Telemetry API を使用してログを取り込む場合にも、Cloud Logging の割り当てと上限が適用されます。