トラブルシューティング¶
次の順に確認してください。
- エージェントのバージョンを確認します。Java JAR のファイル名を確認するか、
beacon --version、npm ls @beacon-observability/nodejs、beacon-dotnet version、vendor/bin/beacon-php --versionを実行してください。 - アプリケーションを起動するプロセスの環境に、
OTEL_SERVICE_NAME、受信アドレス、プロトコルが設定されていることを確認します。 - アプリケーションのホストから受信ポートへのネットワーク接続を確認します。
- 対応するフレームワークやライブラリを経由する実際のリクエストを発生させます。起動するだけでは Span が生成されない場合があります。
- 下の表に従って対象言語の診断を有効にし、問題を再現した後でログを保存し、元の設定に戻します。
言語別のデバッグと診断¶
デバッグの開始方法は言語ごとに異なります。具体的なコマンド、ログの場所、無効にする手順は各言語のページを参照してください。
| 言語 | デバッグまたは診断の方法 | 結果 |
|---|---|---|
| Java | OTEL_JAVAAGENT_DEBUG=true または -Dotel.javaagent.debug=true |
Agent のデバッグログ |
| Python | アプリケーションのログ設定で opentelemetry Logger を調整。初期診断には OTEL_TRACES_EXPORTER=otlp,console を使用可能 |
SDK ログは Python logging 設定に依存。コンソールの Span でテレメトリの生成を確認 |
| Node.js | OTEL_LOG_LEVEL=debug を設定し、既存のプリロード設定を保持 |
端末の診断ログ |
| .NET | OTEL_LOG_LEVEL=debug と OTEL_DOTNET_AUTO_LOG_DIRECTORY を設定 |
指定ディレクトリ内のエージェントログ。beacon-dotnet status でインストール状態を確認 |
| PHP | OTEL_LOG_LEVEL=debug、OTEL_PHP_LOG_DESTINATION=stderr；vendor/bin/beacon-php doctor --json |
SDK の内部ログと実行環境の診断レポート |
これらはエージェント自体の調査用ログであり、OTEL_LOGS_EXPORTER が制御するテレメトリログのエクスポートとは別に設定します。サービス名、OTLP アドレス、読み込み方法を保持したまま一時的に診断を有効にし、問題を一度再現した後は通常の起動設定に戻してください。ログを共有する前に、認証情報とリクエスト内の機密情報を削除してください。
Profile データがない¶
- Java：JDK 11 以降を使用していることと、Profile ディレクトリに書き込めることを確認してください。
- Python と Node.js：
OTEL_PROFILING_ENABLED=true、正しいアップロード先、エクスポート間隔を超えるプロセスの実行時間を確認してください。 - Profile データを OTLP Trace アドレスに送信しないでください。Java は JFR multipart、Python と Node.js は pprof multipart でアップロードします。DataKit では Profile コレクターを有効にする必要があります。
Security データがない¶
- アプリケーションのプロセス環境に
BEACON_SECURITY_ENABLED=trueと OTLP Logs エクスポーターが設定されていることを確認してください。 - Python では
BEACON_SECURITY_PYTHON_INCLUDEにアプリケーションモジュールのプレフィックスを設定します。Node.js ではBEACON_SECURITY_NODE_INCLUDEにアプリケーションのソースルートを設定し、ESM の--importプリロードを使用します。 - ランタイム SBOM はセキュリティ検出結果より先に生成される場合があります。モデル化された source と sink を通る実際のリクエストを発生させてください。起動するだけでは検出結果は生成されません。
BEACON_SECURITY_LOCAL_OUTPUT_ENABLED=trueを設定しない限り、ローカル診断ファイルは無効のままです。ローカルファイルがないことは、OTLP Logs エクスポートの失敗を意味しません。
エージェントを有効にした場合にだけアプリケーションが失敗する場合は、まずエージェントを無効にしてサービスを復旧してください。エージェントのデバッグログ、ランタイムのバージョン、機密情報を削除したコマンドライン、最小限の再現リクエストを保存してください。
DataKit のアドレスやプロトコルが一致しない¶
- OTLP/gRPC は
http://<DataKit-IP>:4317を使用し、HTTP パスを追加しないでください。 - OTLP/HTTP は
http/protobufを使用し、共通アドレスはhttp://<DataKit-IP>:9529/otelです。シグナル専用アドレスには/otel/v1/traces、/otel/v1/metrics、/otel/v1/logsの完全なパスが必要です。 curl http://<DataKit-IP>:9529/v1/pingで確認できるのは DataKit HTTP サービスへの到達性のみです。gRPC ポートや個々のコレクターが有効であることは確認できません。- 別ホストからアクセスする場合はリッスンアドレスとネットワークポリシーを確認してください。コンテナ内の
127.0.0.1は、そのコンテナ自体を指します。
設定と確認の手順は共通設定を参照してください。