Google Cloud Observability での OTLP のサポート

OpenTelemetry プロトコルを実装する Telemetry（OTLP）API を使用して、OTLP 形式のログ、指標、トレースデータを Google Cloud Observability に取り込むことができます。この API を使用すると、カスタム Google Cloud エクスポータを使用せずに、OpenTelemetry SDK とコレクタからベンダーに依存しないテレメトリーを収集できます。

Telemetry API を使用してテレメトリーをプロジェクトに送信すると、Google Cloud Observability は各シグナルを次のように処理します。

  • ログデータ: OTLP ログレコードをログエントリに変換し、保存用に転送します。
  • 指標データ: 指標データを Cloud Monitoring の Prometheus 時系列にマッピングします。
  • トレースデータ: OTLP と概ね一致する形式で分散トレースを保存します。

Google Kubernetes Engine でワークロードを実行している場合は、OpenTelemetry Collector を手動でデプロイして管理する代わりに、GKE 用マネージド OpenTelemetry を使用できます。

プロトコル サポート

OTLP エンドポイントは、http/protobuf、http/json、grpc など、すべての OTLP 転送プロトコルとシリアル化プロトコルをサポートしています。SDK を使用してアプリケーションから直接エクスポートする場合は、ほとんどの SDK エクスポータが動的トークンの更新をサポートしていないため、HTTP エクスポータではなく gRPC OTLP エクスポータを使用することをおすすめします。

認証

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

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

Telemetry API を使用してテレメトリー データを Google Cloud プロジェクトに送信するには、次の操作も行う必要があります。

  • 割り当てプロジェクトを構成します。詳細については、割り当てプロジェクトを設定するをご覧ください。

  • アプリケーションが使用するユーザーまたはサービス アカウントに、次の Identity and Access Management（IAM）ロールを付与します。

    • 割り当てプロジェクトに対するService Usage コンシューマーのロール（roles/serviceusage.serviceUsageConsumer）。
    • プロジェクトに対する Cloud Telemetry 書き込みロール（roles/telemetry.writer）。このロールにより、アプリケーションはログ、指標、トレースデータを書き込むことができます。

OTLP 取り込み

このセクションでは、ログ、指標、トレースデータが OTLP から Google Cloud Observability データ構造に変換される方法について説明します。

ログデータの取り込み

Telemetry API を使用して OTLP 形式のログを取り込むと、ログデータは Cloud Logging のログエントリに変換されます。JSON 形式の受信 OTLP ログ リクエストの一般的な構造は次のとおりです。

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

各 logRecords 配列の各項目は、単一の Cloud Logging ログエントリになります。resource 属性により、結果の LogEntry のモニタリング対象リソースが決まります。OTLP 形式のログの取り込みに必要な属性の詳細については、OTLP 属性とリソースタイプのマッピングをご覧ください。

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

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

resourceLogs 

{
  "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 リソース、スコープ、エンティティ メタデータが各ログエントリにコピーされます。

指標データの取り込み

Prometheus 指標の OTLP は、OpenTelemetry Collector バージョン 0.140.0 以降を使用する場合にのみ機能します。

OpenTelemetry Collector と otlphttp エクスポータを使用して指標が Cloud Monitoring に取り込まれる場合、または OpenTelemetry SDK を使用して直接送信される場合、OTLP 指標は Cloud Monitoring 指標構造にマッピングされます。これらのマッピングに関する情報を取得するには、以下をご覧ください。

Google Cloud Observability は、指標を Prometheus 時系列形式に変換します。指標名にはドメインがないか、ドメイン prometheus.googleapis.com が必要です。変換後、指標名には prometheus.googleapis.com 接頭辞と、OTLP ポイントの種類に基づく追加の接尾辞が含まれます。結果の Cloud Monitoring 指標の構造は次のとおりです。

prometheus.googleapis.com/{metric_name}/{suffix}

また、一意の OpenTelemetry リソースごとに、変換によって service.name、service.instance.id、service.namespace を除くすべてのリソース属性を含む target_info 指標が追加されます。

Cloud Monitoring の指標名とラベルキーは完全な UTF-8 をサポートしていないため、指標データが拒否されることがあります。

  • 正規表現 [a-zA-Z][a-zA-Z0-9_:./-]* に準拠していない指標名は拒否されます。指標名で使用できる特殊文字は _:./- のセットのみです。
  • 正規表現 [a-zA-Z_][a-zA-Z0-9_.]* に準拠していない属性（ラベルキー）を含むデータポイントは拒否されます。ラベルキーで使用できる特殊文字は _. のみです。ラベル値にはすべての特殊文字を使用できます。

これらの理由で指標が拒否されないようにするには、replace_pattern 関数を使用して指標名と属性を変換します。

トレース データの取り込み

Telemetry API を使用するか Cloud Trace API を使用するかにかかわらず、受信したトレースデータは OTLP と一貫性のある形式で保存されます。ただし、Telemetry API は Cloud Trace API よりも取り込み割り当てが大きいため、Telemetry API を使用することをおすすめします。

以下は、アプリケーションから Google Cloud プロジェクトに送信されるトレース データの例です。

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeSpans": [
        {
          "scope": { ...},
          "spans": [...]
        }
      ]
    }
  ]
}

各 scopeSpans.spans 配列の各項目は、単一の保存済みスパンになります。

  • 各スパンの resource フィールドには、resourceSpans.resource.attributes データのコピーが含まれています。
  • 各スパンの instrumentation_scope フィールドには、scopeSpans.scope データのコピーが含まれています。
  • 各スパンは scopeSpans.spans 配列の 1 つのエントリに対応します。traceId、spanId、kind などのフィールドは、トレース スキーマ内の同様の名前のフィールドにマッピングされます。

詳細については、次のドキュメントをご覧ください。

課金

Telemetry API を使用して取り込まれたログ、指標、トレースデータの課金は、テレメトリー シグナルによって異なります。詳細については、お支払いページをご覧ください。

ログデータの課金

Telemetry API を使用してログを取り込むと、ログの量が変わるため、Cloud Logging のストレージと課金の値が変化することがあります。

Google Cloud プロジェクトのストレージと請求に対する最大の変更は、次の両方が当てはまる場合に発生します。

  • resource フィールドに、カーディナリティの高い属性または多数の属性が含まれています。これらのリソース属性によって、結果の LogEntry でモニタリング対象リソースが決まります。
  • scopeLogs フィールドには、logRecords 配列に大量のアイテムが含まれています。scopeLogs.scope フィールドは、個々のログエントリごとに otel フィールドにコピーされます。

このリソースとスコープのメタデータは個々のログエントリにコピーされるため、保存されるログの量が増える可能性があります。

ストレージ ボリュームを最小限に抑えるために、次のことをおすすめします。

  • transform プロセッサなどの OpenTelemetry Collector プロセッサを使用して、データをエクスポートする前に不要なリソース属性またはスコープ属性を削除します。
  • otel フィールドに追加のメタデータを保持する必要がない場合は、以前のマッピング オプション gcp.use_legacy_mapping を使用します。これにより、otel フィールドにデータが入力されなくなります。

指標データの課金

OTLP 指標の課金は、Google Cloud Managed Service for Prometheus の指標に使用されるものと同じ「Prometheus サンプル取り込み」SKU で行われます。

トレースデータの課金

トレースデータをプロジェクトに送信するために使用する API は、そのデータの料金の計算方法には影響しません。

ログ、指標、トレースデータのクエリ

エクスプローラ ページ（ログ エクスプローラ、Metrics Explorer、Trace エクスプローラ）を使用して、ログ、指標、トレースデータをクエリできます。また、[オブザーバビリティ分析] ページで SQL を使用してログデータとトレースデータを分析することもできます。

Metrics Explorer を使用して指標データをクエリする際に、次のヒントが役立つことがあります。

  • 重要: コロン（:）とアンダースコア（_）以外の特殊文字を含む指標名とラベルキーをクエリするには、PromQL の UTF-8 仕様に従って、中かっこ（{}）と引用符（"）で囲む必要があります。たとえば、次のクエリは有効です。

    • {"my.metric.name"}
    • {"my.metric.name", "label.key.KEY"="value"}

  • 指数ヒストグラムのクエリ時に le ラベルを保持すると、予期しない結果が返されることがあります。より一般的な histogram_quantile(.99, sum by (le) (metric)) クエリは機能するはずです。

  • デルタ指標は、デルタが非常に少ない場合など、特定の状況で正しくクエリされないことがあります。

制限と割り当て

Telemetry API の上限は、すべてのシグナルタイプに適用されます。

次の割り当てと上限も適用されます。

  • ログデータ: Cloud Logging API の割り当てと上限が適用されます。

  • 指標データ: Cloud Monitoring API の割り当てと上限が適用されます。たとえば、指標に 200 個を超えるラベルを設定することはできません。

    Telemetry API によって取り込まれる指標のデフォルトの割り当ては、1 分あたり 60,000 リクエストです。リクエストあたりの最大バッチサイズが 200 ポイントの場合、この割り当ては 1 秒あたり 200,000 サンプルの有効なデフォルト割り当てになります。割り当ての増加をリクエストできます。

  • トレースデータ: 適用される追加の割り当てや上限はありません。

次のステップ