OTLP 取り込みの概要

このドキュメントでは、 OpenTelemetry プロトコルを実装する telemetry.googleapis.com Telemetry（OTLP）APIの使用について説明します。 Telemetry API を使用すると、OTLP 形式のログ、指標、トレースデータを Google Cloud Observability に取り込むことができます。

  • OTLP ログレコードはログエントリ に変換され、転送されて保存されます。変換プロセスの詳細については、 このドキュメントの OTLP ログの取り込みをご覧ください。
  • 指標データは Cloud Monitoring に取り込まれます。指標名とラベル名、取り込みの制限については、このドキュメントの OTLP 指標の取り込みをご覧ください。
  • トレースデータは、OTLP と概ね一致する形式で保存されます。 詳細については、OTLP トレースの取り込みをご覧ください。

テレメトリー データは、SDK を使用するアプリケーションから Telemetry API に送信するか、OpenTelemetry Collector からエクスポートできます。

Google Kubernetes Engine を使用している場合は、 GKE 用の Managed OpenTelemetry を使用できます。 Telemetry API を使用する OpenTelemetry Collector を手動でデプロイして構成する必要はありません。

プロトコル サポート

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

認証

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

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

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

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

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

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

OTLP の取り込み

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

ログデータの取り込み

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

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

各 logRecords 配列の各項目は、単一の Cloud Logging ログエントリになります。The 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 リソースごとに、変換によって target_infoを除くすべてのリソース属性を含む指標が追加されます。service.nameservice.instance.idservice.namespace

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 と互換性のある形式で保存されます。 ただし、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 フィールドにコピーされます。

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

ストレージ容量を最小限に抑えるには、次のことをおすすめします。

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

指標データの課金

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

トレースデータの課金

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

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

ログ エクスプローラ、Metrics Explorer、Trace エクスプローラなどのエクスプローラ ページを使用して、ログ、指標、トレースデータをクエリできます。 また、Observability Analytics ページで 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 サンプルの有効なデフォルト割り当てになります。割り当ての増加をリクエストできます。

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

次のステップ