Red Hat Summit Red Hat Summitサポートコンソール開発者トライアルの開始お問い合わせ

Red Hat build of OpenTelemetry のトラブルシューティング

Red Hat build of OpenTelemetry 3.8

Collector およびインストルメンテーションの問題の診断および解決

Red Hat OpenShift Documentation Team

概要

このドキュメントでは、OpenTelemetry Collector およびインストルメンテーションのトラブルシューティング手順を説明します。must-gather を使用して診断データを収集、Collector ログの設定および取得、データ処理のための内部メトリクスの公開と監視、デバッグエクスポーターの使用、およびネットワーク問題のトラブルシューティングを行う方法について説明します。インストルメント化の注入、Pod アノテーションの検証、init-containers の確認、Operator ログの検査、Telemetry データ生成の問題の解決手順が含まれます。

第1章 トラブルシューティング
リンクのコピー

OpenTelemetry Collector のヘルスを測定し、データの取り込みに関する問題を調査する方法は複数あります。

1.1. コマンドラインからの診断データの収集
リンクのコピー

サポートケースを送信するときは、クラスターに関する診断情報を Red Hat サポートに含めると役立ちます。oc adm must-gather ツールを使用すると、OpenTelemetryCollector、Instrumentation などのさまざまなタイプのリソースや、Deployment、Pod、ConfigMap などの作成されたリソースの診断データを収集できます。oc adm must-gather ツールは、このデータを収集する新しい Pod を作成します。

手順

  • 収集したデータを保存するディレクトリーから、oc adm must-gather コマンドを実行してデータを収集します。 

    $ oc adm must-gather --image=ghcr.io/open-telemetry/opentelemetry-operator/must-gather -- \
/usr/bin/must-gather --operator-namespace <operator_namespace>
    1
    Copy to Clipboard Toggle word wrap
    1
    Operator がインストールされるデフォルトの namespace は openshift-opentelemetry-operator です。

検証

  • 新しいディレクトリーが作成され、収集されたデータが含まれていることを確認します。

1.2. OpenTelemetry Collector ログの取得
リンクのコピー

OpenTelemetry Collector のログを取得するには、以下の手順を実行します。

手順

  1. OpenTelemetryCollector カスタムリソース (CR) で関連するログレベルを設定します。 

      config:
    service:
      telemetry:
        logs:
          level: debug
    1
    Copy to Clipboard Toggle word wrap
    1
    Collector のログレベル。サポートされている値には、info、warn、error、または debug が含まれます。デフォルトは info です。
  2. oc logs コマンドまたは Web コンソールを使用してログを取得します。

1.3. メトリクスの公開
リンクのコピー

OpenTelemetry Collector は、処理したデータ量に関する次のメトリクスを公開します。

otelcol_receiver_accepted_spans
パイプラインに正常にプッシュされたスパンの数。
otelcol_receiver_refused_spans
パイプラインにプッシュできなかったスパンの数。
otelcol_exporter_sent_spans
宛先に正常に送信されたスパンの数。
otelcol_exporter_enqueue_failed_spans
送信キューに追加できなかったスパンの数。
otelcol_receiver_accepted_logs
パイプラインに正常にプッシュされたログの数。
otelcol_receiver_refused_logs
パイプラインにプッシュできなかったログの数。
otelcol_exporter_sent_logs
宛先に正常に送信されたログの数。
otelcol_exporter_enqueue_failed_logs
送信キューに追加できなかったログの数。
otelcol_receiver_accepted_metrics
パイプラインに正常にプッシュされたメトリクスの数。
otelcol_receiver_refused_metrics
パイプラインにプッシュできなかったメトリクスの数。
otelcol_exporter_sent_metrics
宛先に正常に送信されたメトリクスの数。
otelcol_exporter_enqueue_failed_metrics
送信キューに追加できなかったメトリクスの数。

これらのメトリクスを使用して、Collector に関する問題をトラブルシューティングできます。たとえば、otelcol_receiver_refused_spans メトリクスの値が高い場合、Collector が着信スパンを処理できないことを示しています。

Operator は、メトリクスエンドポイントのスクレイプに使用できる <cr_name>-collector-monitoring テレメトリーサービスを作成します。

手順

  1. OpenTelemetryCollector カスタムリソース (CR) に次の行を追加して、テレメトリーサービスを有効にします。 

    # ...
  config:
    service:
      telemetry:
        metrics:
          readers:
          - pull:
              exporter:
                prometheus:
                  host: 0.0.0.0
                  port: 8888
    1 
    
# ...
    Copy to Clipboard Toggle word wrap
    1
    内部 Collector のメトリクスが公開されるポート。デフォルトは :8888 です。

  2. ポート転送 Collector Pod を使用する次のコマンドを実行して、メトリクスを取得します。 

    $ oc port-forward <collector_pod>
    Copy to Clipboard Toggle word wrap

  3. OpenTelemetryCollector CR で、enableMetrics フィールドを true に設定して内部メトリクスをスクレイピングします。 

    apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
spec:
# ...
  mode: deployment
  observability:
    metrics:
      enableMetrics: true
# ...
    Copy to Clipboard Toggle word wrap

    OpenTelemetry Collector のデプロイメントモードに応じて、PodMonitors または ServiceMonitors を使用して内部メトリクスがスクレイピングされます。

    注記

    または、enableMetrics フィールドを true に設定しない場合は、http://localhost:8888/metrics でメトリクスエンドポイントにアクセスできます。

  4. オプション: Web コンソールで ユーザーワークロードモニタリング 機能が有効になっている場合は、Web コンソールで Observe → Dashboards に移動し、ドロップダウンリストから OpenTelemetry Collector ダッシュボードを選択して表示します。ユーザーワークロードモニタリング 機能の詳細は、モニタリング の「ユーザー定義プロジェクトのモニタリングの有効化」を参照してください。

    ヒント

    スパンやメトリクスなどの視覚化されたデータは、Collector インスタンス、namespace、またはプロセッサー、レシーバー、エクスポーターなどの OpenTelemetry コンポーネント別にフィルタリングできます。

1.4. Debug Exporter
リンクのコピー

収集したデータを標準出力にエクスポートするように Debug Exporter を設定できます。

手順

  1. OpenTelemetryCollector カスタムリソースを次のように設定します。 

      config:
    exporters:
      debug:
        verbosity: detailed
    service:
      pipelines:
        traces:
          exporters: [debug]
        metrics:
          exporters: [debug]
        logs:
          exporters: [debug]
    Copy to Clipboard Toggle word wrap
  2. oc logs コマンドまたは Web コンソールを使用して、ログを標準出力にエクスポートします。

1.5. ネットワークポリシーの無効化
リンクのコピー

Red Hat build of OpenTelemetry Operator は、セキュリティーを強化するためのネットワークポリシーを作成し、Operator およびオペランドのトラフィックを制御します。デフォルトでは、ネットワークポリシーが有効になっており、必要なすべてのコンポーネントへのトラフィックを許可するように設定されています。追加の設定は必要ありません。

OpenTelemetry Collector またはその Target Allocator コンポーネントでトラフィックの問題が発生する場合、デフォルトのネットワークポリシー設定が原因で問題が発生している可能性があります。問題をトラブルシューティングするには、OpenTelemetry Collector のネットワークポリシーを無効化できます。

前提条件

  • cluster-admin ロールを持つクラスター管理者としてクラスターにアクセスできる。

手順

  • OpenTelemetryCollector カスタムリソース (CR) を設定して、OpenTelemetry Collector のネットワークポリシーを無効にします。 

    apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
  name: otel
  namespace: observability
spec:
  networkPolicy:
    enabled: false
    1 
    
  # ...
    Copy to Clipboard Toggle word wrap
    1
    networkPolicy.enabled を true (デフォルト) または false に設定して、ネットワークポリシーを有効にするかどうかを指定します。false に設定すると、ネットワークポリシーの作成が無効になります。

1.6. Network Observability Operator を使用したトラブルシューティング
リンクのコピー

Network Observability Operator を使用して可観測性コンポーネント間のトラフィックを可視化することで、トラフィックをデバッグできます。

前提条件

  • 「Network Observability Operator のインストール」の説明に従って、Network Observability Operator をインストールした。

手順

  1. OpenShift Container Platform Web コンソールで、Observe → Network Traffic → Topology に移動します。
  2. Namespace を選択し、OpenTelemetry Collector がデプロイされている namespace でワークロードをフィルタリングします。
  3. ネットワークトラフィックのビジュアルを使用して、考えられる問題をトラブルシューティングします。詳細は、「トポロジービューからのネットワークトラフィックの観察」を参照してください。

1.7. 計装のトラブルシューティング
リンクのコピー

計装のトラブルシューティングを行うには、次のいずれかの問題を確認します。

  • ワークロードへの計装の注入に関する問題
  • 計装ライブラリーによるデータ生成に関する問題

1.7.1. ワークロードへの計装注入のトラブルシューティング
リンクのコピー

計装注入のトラブルシューティングを行う際には、次の作業を実行できます。

  • Instrumentation オブジェクトが作成されたかどうかを確認する
  • init-container が起動したかどうかを確認する
  • リソースが正しい順序でデプロイされたかどうかを確認する
  • Operator ログのエラーを検索する
  • Pod アノテーションを再確認する

手順

  1. 次のコマンドを実行して、Instrumentation オブジェクトが正常に作成されたことを確認します。 

    $ oc get instrumentation -n <workload_project>
    1
    Copy to Clipboard Toggle word wrap
    1
    計装が作成された namespace。

  2. 次のコマンドを実行して、ワークロードへの計装注入の前提条件である opentelemetry-auto-instrumentation init-container が正常に起動したことを確認します。 

    $ oc get events -n <workload_project>
    1
    Copy to Clipboard Toggle word wrap
    1
    ワークロードの計装が注入された namespace。

    出力例

    ... Created container opentelemetry-auto-instrumentation
... Started container opentelemetry-auto-instrumentation
    Copy to Clipboard Toggle word wrap

  3. 自動計装が正しく機能するように、リソースが正しい順序でデプロイされたことを確認します。アプリケーションの前に Instrumentation カスタムリソース (CR) をデプロイするのが正しい順序です。Instrumentation CR の詳細は、「計装の設定」セクションを参照してください。

    注記

    Pod が起動すると、Red Hat build of OpenTelemetry Operator が、自動計装を注入するための指示を含むアノテーションが Instrumentation CR にあるかどうかを確認します。通常、この Operator はアプリケーションの Pod に init コンテナーを追加し、自動計装と環境変数をアプリケーションのコンテナーに注入します。アプリケーションのデプロイ時に Operator が Instrumentation CR を利用できない場合、Operator は自動計装を注入できません。

    デプロイメントの順序を修正するには、次の手順が必要です。

    1. 計装の設定を更新します。
    2. Instrumentation オブジェクトを削除します。
    3. アプリケーションを再デプロイします。

  4. 次のコマンドを実行して、Operator ログで計装のエラーを調べます。 

    $ oc logs -l app.kubernetes.io/name=opentelemetry-operator --container manager -n openshift-opentelemetry-operator --follow
    Copy to Clipboard Toggle word wrap

  5. 特定プログラミング言語の計装用の Pod アノテーションをトラブルシューティングします。「計装の設定」で必要なアノテーションフィールドと値を参照してください。

    1. 計装するアプリケーションの Pod に正しいアノテーションが付けられ、適切な自動計装設定が適用されていることを確認します。

      例

      instrumentation.opentelemetry.io/inject-python="true"
      Copy to Clipboard Toggle word wrap

      計装された Python アプリケーションの Pod アノテーションを取得するコマンドの例

      $ oc get pods -n <workload_project> -o jsonpath='{range .items[?(@.metadata.annotations["instrumentation.opentelemetry.io/inject-python"]=="true")]}{.metadata.name}{"\n"}{end}'
      Copy to Clipboard Toggle word wrap

    2. Instrumentation オブジェクトに適用されたアノテーションが、計装するプログラミング言語に対して正しいことを確認します。

    3. 同じ namespace に複数の計装がある場合は、それらのアノテーションに Instrumentation オブジェクトの名前を指定します。

      例

      instrumentation.opentelemetry.io/inject-nodejs: "<instrumentation_object>"
      Copy to Clipboard Toggle word wrap

    4. Instrumentation オブジェクトが別の namespace にある場合は、アノテーションでその namespace を指定します。

      例

      instrumentation.opentelemetry.io/inject-nodejs: "<other_namespace>/<instrumentation_object>"
      Copy to Clipboard Toggle word wrap

    5. OpenTelemetryCollector カスタムリソースの spec.template.metadata.annotations の下に自動計装のアノテーションが指定されていることを確認します。spec.metadata.annotations に自動計装のアノテーションがある場合は、spec.template.metadata.annotations に移動します。

1.7.2. 計装ライブラリーによるテレメトリーデータ生成のトラブルシューティング
リンクのコピー

エンドポイントを確認し、アプリケーションログでエラーを探し、Collector がテレメトリーデータを受信していることを確認することで、計装ライブラリーによるテレメトリーデータ生成のトラブルシューティングを行うことができます。

手順

  1. 計装が正しいエンドポイントにデータを送信していることを確認します。 

    $ oc get instrumentation <instrumentation_name> -n <workload_project> -o jsonpath='{.spec.endpoint}'
    Copy to Clipboard Toggle word wrap

    Instrumentation オブジェクトのデフォルトのエンドポイント http://localhost:4317 は、アプリケーション Pod にサイドカーとしてデプロイされた Collector インスタンスにのみ適用されます。間違ったエンドポイントを使用している場合は、Instrumentation オブジェクトを編集してアプリケーションを再デプロイすることで修正します。

  2. アプリケーションログを調べて、計装が誤動作していることを示すエラーメッセージがないか確認します。 

    $ oc logs <application_pod> -n <workload_project>
    Copy to Clipboard Toggle word wrap
  3. アプリケーションログに、計装が誤動作している可能性があることを示すエラーメッセージが含まれている場合は、OpenTelemetry SDK とライブラリーをローカルにインストールします。次に、アプリケーションをローカルで実行し、OpenShift Container Platform を使用せずに、計装ライブラリーとアプリケーション間の問題をトラブルシューティングします。
  4. Debug Exporter を使用して、テレメトリーデータが宛先の OpenTelemetry Collector インスタンスに到達していることを確認します。詳細は、「Debug Exporter」を参照してください。

法律上の通知
リンクのコピー

Copyright © 2025 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。 最新の更新を見る.

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

Theme

© 2026 Red Hatトップに戻る