トラブルシューティング
このページでは、OpenTelemetryコレクターの健全性とパフォーマンスに関するトラブルシューティングの方法を学ぶことができます。
トラブルシューティングツール
コレクターは、問題のデバッグのために様々なメトリクス、ログ、拡張機能を提供します。
内部テレメトリー
コレクター自身の内部テレメトリーを設定して使用することで、そのパフォーマンスを監視できます。
ローカルエクスポーター
設定の検証やネットワークのデバッグなど、特定の問題については、ローカルログに出力するように設定されたコレクターに少量のテストデータを送信できます。 ローカルエクスポーターを使用することで、コレクターによって処理されているデータを検査できます。
ライブトラブルシューティングには、コレクターがデータを受信、処理、エクスポートしていることを確認できるデバッグ
エクスポーターの使用を検討してください。
例を挙げましょう。
receivers:
zipkin:
exporters:
debug:
service:
pipelines:
traces:
receivers: [zipkin]
processors: []
exporters: [debug]
テストを開始するには、Zipkinペイロードを生成します。
たとえば、 trace.json
という名前のファイルを以下の内容で作成できます。
[
{
"traceId": "5982fe77008310cc80f1da5e10147519",
"parentId": "90394f6bcffb5d13",
"id": "67fae42571535f60",
"kind": "SERVER",
"name": "/m/n/2.6.1",
"timestamp": 1516781775726000,
"duration": 26000,
"localEndpoint": {
"serviceName": "api"
},
"remoteEndpoint": {
"serviceName": "apip"
},
"tags": {
"data.http_response_code": "201"
}
}
]
コレクターが実行している状態で、このペイロードをコレクターに送信します。
curl -X POST localhost:9411/api/v2/spans -H'Content-Type: application/json' -d @trace.json
以下のようなログエントリが表示されるはずです。
2023-09-07T09:57:43.468-0700 info TracesExporter {"kind": "exporter", "data_type": "traces", "name": "debug", "resource spans": 1, "spans": 2}
ペイロード全体が出力されるように デバッグ
エクスポーターを設定することもできます。
exporters:
debug:
verbosity: detailed
設定を変更して前回のテストを再実行すると、ログ出力は次のようになります。
2023-09-07T09:57:12.820-0700 info TracesExporter {"kind": "exporter", "data_type": "traces", "name": "debug", "resource spans": 1, "spans": 2}
2023-09-07T09:57:12.821-0700 info ResourceSpans #0
Resource SchemaURL: https://opentelemetry.io/schemas/1.4.0
Resource attributes:
-> service.name: Str(telemetrygen)
ScopeSpans #0
ScopeSpans SchemaURL:
InstrumentationScope telemetrygen
Span #0
Trace ID : 0c636f29e29816ea76e6a5b8cd6601cf
Parent ID : 1a08eba9395c5243
ID : 10cebe4b63d47cae
Name : okey-dokey
Kind : Internal
Start time : 2023-09-07 16:57:12.045933 +0000 UTC
End time : 2023-09-07 16:57:12.046058 +0000 UTC
Status code : Unset
Status message :
Attributes:
-> span.kind: Str(server)
-> net.peer.ip: Str(1.2.3.4)
-> peer.service: Str(telemetrygen)
コレクターコンポーネントの確認
以下のサブコマンドを使用して、Collectorディストリビューションで利用可能なコンポーネントとその安定性のレベルを一覧表示します。 出力形式はバージョンによって変更される可能性があることに注意してください。
otelcol components
以下は出力例です。
buildinfo:
command: otelcol
description: OpenTelemetry Collector
version: 0.96.0
receivers:
- name: opencensus
stability:
logs: Undefined
metrics: Beta
traces: Beta
- name: prometheus
stability:
logs: Undefined
metrics: Beta
traces: Undefined
- name: zipkin
stability:
logs: Undefined
metrics: Undefined
traces: Beta
- name: otlp
stability:
logs: Beta
metrics: Stable
traces: Stable
processors:
- name: resource
stability:
logs: Beta
metrics: Beta
traces: Beta
- name: span
stability:
logs: Undefined
metrics: Undefined
traces: Alpha
- name: probabilistic_sampler
stability:
logs: Alpha
metrics: Undefined
traces: Beta
exporters:
- name: otlp
stability:
logs: Beta
metrics: Stable
traces: Stable
- name: otlphttp
stability:
logs: Beta
metrics: Stable
traces: Stable
- name: debug
stability:
logs: Development
metrics: Development
traces: Development
- name: prometheus
stability:
logs: Undefined
metrics: Beta
traces: Undefined
connectors:
- name: forward
stability:
logs-to-logs: Beta
logs-to-metrics: Undefined
logs-to-traces: Undefined
metrics-to-logs: Undefined
metrics-to-metrics: Beta
traces-to-traces: Beta
extensions:
- name: zpages
stability:
extension: Beta
- name: health_check
stability:
extension: Beta
- name: pprof
stability:
extension: Beta
拡張機能
以下は、コレクターのデバッグのために有効にできる拡張機能のリストです。
パフォーマンスプロファイラ (pprof)
ローカルのポート 1777
で利用可能なpprof 拡張機能を使用すると、実行中のコレクターをプロファイリングできます。
これは高度なユースケースであり、ほとんどの状況では必要ないはずです。
zPages
zPages 拡張機能は、コレクターのレシーバーとエクスポーターからのライブデータを検査するために使用できます。
/debug/tracez
で公開されるTraceZページは、次のようなトレース操作のデバッグに役立ちます。
- レイテンシーの問題。アプリケーションの遅い部分を特定します。
- デッドロックと計装の問題。終了しない実行中のスパンを特定します。
- エラー。発生しているエラーの種類と発生場所を特定します。
zpages
には、コレクター自体が出力しないエラーログが含まれている場合があることに注意してください。
コンテナ環境では、このポートをローカルだけでなくパブリックインターフェースで公開したい場合があります。
endpoint
は extensions
設定セクションを使用して構成できます。
extensions:
zpages:
endpoint: 0.0.0.0:55679
複雑なパイプラインをデバッグするためのチェックリスト
テレメトリーが複数のコレクターやネットワークを経由して流れる場合、問題を特定するのは困難な場合があります。 テレメトリーがコレクターやパイプライン内の他のコンポーネントを通過する各"ホップ"で、以下を確認することが重要です。
- コレクターのログにエラーメッセージはありますか?
- テレメトリーはこのコンポーネントにどのように取り込まれていますか?
- テレメトリーはこのコンポーネントによってどのように変更(たとえば、サンプリングやリダクション)されていますか?
- テレメトリーはこのコンポーネントからどのようにエクスポートされていますか?
- テレメトリーはどの形式ですか?
- 次のホップはどのように設定されていますか?
- データの出入りを妨げるネットワークポリシーはありますか?
一般的なコレクターの問題
このセクションでは、一般的なコレクターの問題を解決する方法について説明します。
コレクターでデータに関する問題が発生している
コレクターとそのコンポーネントでデータの問題が発生することがあります。
コレクターがデータをドロップしている
コレクターがデータをドロップする理由は様々ですが、最も一般的なものは次のとおりです。
- コレクターのサイジングが不適切で、受信したデータを処理してエクスポートする速度が追いつかない。
- エクスポーターの宛先が利用できないか、データの受け入れが遅すぎる。
ドロップを軽減するには、batch
プロセッサーを設定します。
さらに、有効化されているエクスポーターでキューリトライオプションを設定する必要があるかもしれません。
コレクターがデータを受信していない
コレクターがデータを受信しない理由は次のとおりです。
- ネットワーク設定の問題。
- レシーバー設定の誤り。
- クライアント設定の誤り。
- レシーバーが
レシーバーズ
セクションで定義されているが、どのパイプライン
でも有効になっていない。
潜在的な問題については、コレクターのlogs とzPagesを確認してください。
コレクターがデータを処理していない
ほとんどの処理の問題は、プロセッサーの動作に関する誤解やプロセッサーの誤った設定が原因です。 例を挙げましょう。
- アトリビュートプロセッサーはスパンの"タグ"にのみ機能します。スパン名はスパンプロセッサーによって処理されます。
- トレースデータのプロセッサー(テールサンプリングを除く)は、個々のスパンに対してのみ機能します。
コレクターがデータをエクスポートしていない
コレクターがデータをエクスポートしない理由は次のとおりです。
- ネットワーク設定の問題。
- エクスポーター設定の誤り。
- 宛先が利用できない。
潜在的な問題については、コレクターのlogs とzPagesを確認してください。
データのエクスポートが機能しないのは、ファイアウォール、DNS、プロキシの問題など、ネットワーク設定の問題が原因であることがよくあります。 コレクターにはプロキシのサポートがあることに注意してください。
コレクターで制御に関する問題が発生している
コレクターで起動の失敗や予期せぬ終了、再起動が発生することがあります。
コレクターが終了または再起動する
コレクターが終了または再起動する原因は次のとおりです。
memory_limiter
プロセッサーがないこと、もしくは設定ミスによるメモリ逼迫。- 負荷に対する不適切なサイジング。
- 不適切な設定。たとえば、利用可能なメモリよりも大きいサイズのキュー。
- インフラストラクチャのリソース制限。たとえば、Kubernetesなど。
Windows Dockerコンテナでコレクターの起動に失敗する
v0.90.1以前では、Windows DockerコンテナでCollectorの起動に失敗し The service process could not connect to the service controller
というエラーメッセージが表示されることがあります。
この場合、NO_WINDOWS_SERVICE=1
環境変数を設定して、コレクターがWindowsサービスとして実行しようとせずに、インタラクティブなターミナルで実行されているかのように強制的に起動させる必要があります。
コレクターで設定に関する問題が発生している
設定の問題により、コレクターで問題が発生することがあります。
Nullマップ
複数の設定ファイルを解決する際、後の設定値がnullであっても、前の設定ファイルの値は後の設定ファイルの値に置き換えられて削除されます。 この問題は、以下の方法で修正できます。
processors:
のかわりにprocessors: {}
のように、空のマップを表すために{}
を使用する。processors:
のような空の設定を構成から省略する。
詳細については、confmapのトラブルシューティングを参照してください。
フィードバック
このページは役に立ちましたか?
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!