Google が構築した OpenTelemetry Collector のトラブルシューティング

このドキュメントでは、Google が構築した OpenTelemetry Collector などの OpenTelemetry Collector を使用してデータを Google Cloud Observability に送信する際のトラブルシューティングの手順と一般的な問題について説明します。

データの収集のトラブルシューティング

このセクションでは、データ収集に関する問題のトラブルシューティングに使用できる戦略について説明します。

debug エクスポータを使用する

debugエクスポータ は、OpenTelemetry Collector レベルでデータを表示するのに最適な方法です。エクスポータは、受信したデータを人が読める形式で stdout に書き込みます。これは、パイプライン内の変換が意図した結果を生成していることを確認する必要がある場合に最も役立ちます。

debug エクスポータは、Google が構築した OpenTelemetry Collector に含まれています。debug エクスポータを verbosity: detailed で構成すると、テレメトリー ペイロード全体を確認できます。

exporters:
  debug:
    verbosity: detailed

エクスポータをパイプラインに含めることができます。

service:
  pipelines:
    metrics:
      receivers: [
        # ...
      ]
      processors: [
        # ...
      ]
      exporters: [
        debug, # can be added alongside any other configured exporters
        # ...
      ]

OTTL Playground で OpenTelemetry Transformation Language（OTTL）をオンラインでテストする

OTTL Playground は、OpenTelemetry Transformation Language パイプラインを インタラクティブに開発できる、コミュニティが開発したツールです。まず、OTLP JSON を入力として指定し、OpenTelemetry Collector と同じ構成を使用してパイプラインを記述し、結果を視覚的に確認します。

パイプラインから OTLP JSON を取得する最適な方法は、変換プロセッサの前の場所に fileエクスポータ を配置することです。まず、file エクスポータを構成します。

exporters:
  file:
    path: example.json

次のようなパイプラインがあるとします。

service:
  pipelines:
    metrics:
      receivers: [hostmetrics]
      processors: [
        memorylimiter,
        groupbyattrs,
        transform, # where your OTTL pipeline will go
        cumulativetodelta,
        metricstarttime,
      ]
      exporters: [
        otlp,
      ]

パイプラインを一時的に変更して、処理中の transform プロセッサに入るデータをエクスポートできます。

service:
  pipelines:
    metrics:
      receivers: [hostmetrics]
      processors: [
        memorylimiter,
        groupbyattrs,
        # transform,
        # cumulativetodelta,
        # metricstarttime,
      ]
      exporters: [
        # otlp,
        file,
      ]

file エクスポータは、受信した各ペイロードをファイルの 1 行に書き込みます。OTTL Playground への入力として、1 行のデータを使用できます。

既知の問題

このセクションでは、OpenTelemetry Collector/Google が構築した OpenTelemetry Collector の既知の問題と、可能な場合はその回避策について説明します。

otlp エクスポータを使用すると、connect: network is unreachable エラーが多すぎる

注: この問題は、HTTP 相当のエクスポータ otlphttp ではなく、gRPC otlp エクスポータにのみ適用されます。

注: この問題は、これまでのところ Compute Engine 環境でのみ直接確認されていますが、問題の性質上、Compute Engine に限定されていることを確認できません。

Google が構築した OpenTelemetry Collector バージョン 0.147.0 以降とアップストリームの OpenTelemetry Collector バージョン 0.145.0 以降では、otlp エクスポータ のデフォルトのクライアントサイド ロード バランシング戦略が pick_first から round_robin に変更されます。エクスポータが以前に pick_first 戦略を使用していた場合、IPV6 が機能しないシナリオでは、完全に機能する IPV4 フォールバックも使用できました。round_robin 戦略にはこのプロパティがなく、エクスポータの起動時に解決されたすべてのアドレスに、機能しない場合でも繰り返し送信を試みます。

そのため、otlp エクスポータを使用してテレメトリー API にデータを送信すると、次のようなエラー メッセージが表示されることがあります。

2026-02-13T20:50:00.665Z        warn    grpc@v1.78.0/clientconn.go:1526 [core] [Channel #1 SubChannel #18] grpc: addrConn.createTransport failed to connect to {Addr: "[2607:f8b0:4001:c62::5f]:443", ServerName: "telemetry.googleapis.com:443", }. Err: connection error: desc = "transport: Error while dialing: dial tcp [2607:f8b0:4001:c62::5f]:443: connect: network is unreachable"   {"resource": {"service.instance.id": "feb467f0-ecc6-4a0c-b1e2-90c908131fdd", "service.name": "otelcol-google", "service.version": "v0.147.0"}, "grpc_log": true}

ログの実際のエラーを分離する:

transport: Error while dialing: dial tcp [2607:f8b0:4001:c62::5f]:443: connect: network is unreachable

このエラーを回避するには、otlphttp エクスポータ に切り替える（例については、OTLP 指標のユーザーガイドをご覧ください）か、otlp エクスポータで pick_first バランサを手動で構成します。

exporters:
  otlp:
    # ...
    balancer_name: pick_first
    # ...

いずれの回避策でもエラーが解決しない場合は、このエラー メッセージが実際のネットワーク接続の問題の兆候である可能性があるため、コレクタが実際にネットワークに到達できることを確認する必要があります。