セルフトラブルシューティング

ログの確認方法

トラブルシューティングの最初のステップは、コンテナのログを確認することです。関連するコマンドを以下に示します：

QoS Agent：

docker compose -f lti_qos-agent.yml logs

Reflector：

docker compose -f lti_reflector.yml logs

Analyzer（lti_analyzerディレクトリ内から実行）：

docker logs lti_analyzer_kafka_1
docker logs lti_analyzer_influxdb_1
docker logs lti_analyzer_influx-writer_1

ダッシュボードにデータが表示されない

http://YOUR_ANALYZER_HOST_IP:12021のダッシュボードにアクセスできるがデータが表示されない場合は、以下のチェックリストを確認してください。

1. アナライザーのコンテナは稼働していますか？

lti_analyzerディレクトリから、Kafka、InfluxDB、influx-writer、Grafanaのコンテナが起動していることを確認します。エラーのログを確認してください。

2. エージェントはアナライザーに到達できますか？

エージェントはlti_qos-agent.ymlのmsgbus.latence.caエクストラホストエントリを介してアナライザーに接続します。設定されているIPがアナライザーホストの正しいIPであること、およびポート12092（Kafka）がエージェントホストからアクセス可能であることを確認してください。

トラフィックがKafkaに実際に到達しているか確認するには、アナライザーホストで以下を実行します（異なる場合はdocker0をお使いのブリッジインターフェースに置き換えてください）：

sudo tcpdump -i docker0 "dst port 12092" -n -c 20

パケットが表示された場合、エージェントは正常にデータを送信しています。数秒以内に何も表示されない場合、エージェントはアナライザーに到達できていません。エージェントホストで以下を実行して、送信していることを確認することもできます：

# ANALYZER_IPをアナライザーホストの実際のIPに置き換えてください
sudo tcpdump -i docker0 "dst ANALYZER_IP and dst port 12092" -n -c 20

ネットワークインターフェースについての注意： tcpdumpで使用するインターフェースは、Dockerコンテナの設定方法によって異なります。ブリッジモード（デフォルト）ではdocker0を使用します。ホストネットワークモードでは、ip route | grep defaultで確認できるメインのネットワークインターフェースを使用します。

3. リフレクターのIPは正しいですか？

lti_qos-agent.ymlのLTI_reflectorがリフレクターホストの正しいIPまたはホスト名を指していることを確認してください。

4. リフレクターのポートは開いていますか？

実行しているプロトコルに応じて、リフレクターホストで以下のポートを開く必要があります：

プロトコル	ポート
HTTP	TCP 12080
HTTPS	TCP 12443
TCP	TCP 12023
UDP	UDP 12024
TWAMP	TCP 12862、UDP 12800–12819
Traffic capacity	TCP/UDP 12501
LIFBE	TCP/UDP 12550
Packet Loss	TCP/UDP 12555

5. ライセンスは有効で、実行中のエージェント数をカバーしていますか？

lti_qos-agent.ymlとlti_reflector.ymlの両方でLTI_license_keyが正しいことを確認してください。ライセンスで許可されているよりも多くのエージェントを実行している場合、一部のエージェントはデータを送信できない場合があります。

6. すべてのエージェントは一意のIDを持っていますか？

各エージェントはLTI_agent_idに対して個別の整数値を持つ必要があります。同じIDを共有する2つのエージェントはデータの競合を引き起こします。

ダッシュボードで一部のプロトコルが表示されない

それらのプロトコルはエージェント設定で無効になっていますか？

プロトコルはlti_qos-agent.ymlでインターバルを-1に設定することで無効になります。例えば、LTI_iperf3_session_interval=-1はiPerf3を無効にします。期待されるプロトコルが-1に設定されていないことを確認してください。

対応するリフレクターのポートは開いていますか？

各プロトコルはリフレクターホストで特定のポートを開く必要があります（上記の表を参照）。ポートがブロックされていると、そのプロトコルの測定は静かに失敗します。

各プロトコルのトラフィックが実際に送受信されているかどうかを確認できます。エージェントホストでこれらを実行します（REFLECTOR_IPを置き換え、正しいインターフェースを使用してください）：

# プロトコルごとにリフレクターへの送信トラフィックを確認
sudo tcpdump -i docker0 "dst REFLECTOR_IP and dst port 12080" -n -c 20   # HTTP
sudo tcpdump -i docker0 "dst REFLECTOR_IP and dst port 12443" -n -c 20   # HTTPS
sudo tcpdump -i docker0 "dst REFLECTOR_IP and dst port 12023" -n -c 20   # TCP
sudo tcpdump -i docker0 "dst REFLECTOR_IP and dst port 12024" -n -c 20   # UDP
sudo tcpdump -i docker0 "dst REFLECTOR_IP and dst port 12862" -n -c 20   # TWAMP control
sudo tcpdump -i docker0 "dst REFLECTOR_IP and dst portrange 12800-12819" -n -c 20  # TWAMP data

# リフレクターからの応答が返ってきているか確認
sudo tcpdump -i docker0 "src REFLECTOR_IP" -n -c 20

リフレクターホストからトラフィックを受信しているかどうかを確認することもできます：

# INTERFACEをリフレクターホストの正しいインターフェースに置き換えてください
sudo tcpdump -i INTERFACE "dst port 12080 or dst port 12443 or dst port 12023 or dst port 12024" -n -c 20
sudo tcpdump -i INTERFACE "dst portrange 12800-12819" -n -c 20  # TWAMP data ports

トラフィックがリフレクターに到達しているが応答がエージェントに返ってこない場合、問題はリフレクター側にある可能性が高いです（コンテナが未起動、ポートが公開されていない）。トラフィックがリフレクターに全く到達しない場合、問題はネットワークレベルです（ファイアウォール、ルーティング、IPが間違っている）。

複数のネットワークインターフェースによるルーティングの問題

リフレクターまたはアナライザーを実行しているVMに複数のネットワークインターフェースがある場合、ルーティングテーブルによって非対称ルーティングが発生する可能性があります：トラフィックが1つのインターフェースに到着するが、応答は別のインターフェースから送信されます。エージェントは返信を受け取らないため、測定が失敗またはタイムアウトします。

これが発生しているかどうかを確認するには、リフレクターまたはアナライザーホストの各インターフェースでtcpdumpを実行し、どのインターフェースが実際に受信トラフィックを受け取っているかを確認します：

# 利用可能なインターフェースを一覧表示
ip link show

# 各インターフェースで受信測定トラフィックを監視
sudo tcpdump -i eth0 "dst port 12080 or dst port 12023 or dst port 12862" -n -c 10
sudo tcpdump -i eth1 "dst port 12080 or dst port 12023 or dst port 12862" -n -c 10
# 各インターフェースについて繰り返す

トラフィックがeth1に到達しているがデフォルトルートがeth0経由で応答を送信している場合、応答はエージェントに届きません。解決策は、リクエストが受信したのと同じインターフェースから応答を送信するポリシールーティングルールを追加することです。これは通常、Linuxのip ruleとip routeで行われます。

iPerf3の結果が0またはエラーが表示される

iPerf3は1回のテストで大量のデータを転送するため、MTUの制限に敏感です。エージェントとリフレクター間のパスのMTUが予想より低い場合、大きなパケットはドロップまたは断片化され、テストは0を返すか完全に失敗しますが、他のプロトコル（より小さいパケットを使用するもの）は正常に動作し続けます。

パスの有効なMTUを確認するには、エージェントホストから「断片化しない」フラグと段階的に大きなパケットサイズでpingを実行します：

# パケットが失敗し始めるまでサイズを大きくして試してください（-M do = 断片化しない、-s = ペイロードサイズ）
ping -M do -s 1400 REFLECTOR_IP -c 3
ping -M do -s 1450 REFLECTOR_IP -c 3
ping -M do -s 1472 REFLECTOR_IP -c 3

成功する最大サイズ（IP+ICMPヘッダーの28バイトを加算）がそのパスの有効なMTUです。1500未満の場合、ネットワークのどこかにMTU制限があります。

lti_qos-agent.ymlのiPerf3バッファ長を有効なMTUに収まるように下げることで回避できます：

- LTI_iperf3_buffer_length=1200

メタデータがダッシュボードで最新でない

メタデータはデフォルトで毎週、またはQoS-Agentの再起動ごとに更新されます。更新されていることを確認するには、以下を使用してエージェントコンテナを再起動できます：

# コンテナを停止
docker compose -f lti_qos-agent.yml down

# コンテナを起動
docker compose -f lti_qos-agent.yml up -d

GPS/ラジオデータが表示されない

実行中のエージェントは次の2つのタイプのいずれかである必要があります： - モバイルアプリエージェント - lti-cradlepoint-dataコンテナを使用するCradlepointエージェント

モバイルアプリエージェント

アプリが独自のアナライザーにデータを送信するように設定されていることを確認してください：

アプリの設定を開く
LTIライセンスキーフィールドにライセンスキーを入力する
InfluxDB URLをポート12086のアナライザーアドレスに設定する： http://YOUR_ANALYZER_IP:12086/
保存を押す

正しいInfluxDB URLがないと、アプリはアナライザーにデータを送信せず、ダッシュボードには何も表示されません。

Androidの場合、アプリ設定でフォアグラウンドサービスが有効になっていることも確認してください。無効になっていると、アプリが最小化または画面がロックされた際に測定の送信を停止する可能性があります。

AndroidでアプリがクラッシュするΑΝ場合： 1. 設定 > アプリ > MobileLatency > 強制停止に移動する 2. ストレージとキャッシュ > キャッシュを消去に移動する 3. アプリを再起動する

Cradlepointエージェント

GPSとラジオデータにはコンテキストエージェント設定が必要で、同じcomposeファイルにlti-cradlepoint-dataコンテナとqos-agentコンテナの両方が含まれます。標準の単一コンテナ設定ではGPSやラジオデータを収集しません。

Cradlepoint composeの設定で以下を確認してください：

qos-agent:latestではなくqos-agent:cradlepointイメージを使用している
lti-cradlepoint-dataコンテナがcomposeファイルに存在する
LTI_cradlepointapi_ipがlti-cradlepoint-dataに設定されている
両方のコンテナが同じネットワーク上にある（例：cradle-network）
LTI_agent_idが両方のコンテナで同じである

Cradlepointデバイス自体でGPSが有効になっていることも確認してください：

NetCloud ManagerでDEVICES > Configuration > Edit > SYSTEM > GPSに移動する
Enable GPSオプションにチェックを入れる

コンテナが起動しない

ライセンスキーは正しいですか？

エージェントとリフレクターの両方に有効なLTI_license_keyが必要です。無効または期限切れのキーはコンテナの起動を妨げます。

必要なパラメータはすべて設定されていますか？

設定ファイルにREPLACE_BY_*プレースホルダー値が残っていないことを確認してください。エージェントに必要なパラメータは：LTI_agent_id、LTI_customer_id、LTI_license_key、LTI_reflector、およびmsgbus.latence.caのIPです。リフレクターに必要なパラメータは：LTI_reflector_idとLTI_license_keyです。

LTI_agent_id、LTI_customer_id、LTI_reflector_idは整数でなければなりません。

レジストリからイメージをプルできますか？

docker compose pullが失敗する場合、ホストがregistry.latence.caに到達できることを確認してください。

Docker v2を使用していますか？

正しいコマンドはdocker compose（スペースあり、ダッシュなし）です。docker-compose（v1）を使用すると問題が発生する可能性があります。

AI機能

チャットボットに「Bad Gateway」エラーが表示される

チャットボットは3つの要素が同時に正常である必要があります：

インターネット接続 — チャットボットはOpenAIを使用するため、アナライザーホストからの送信インターネットアクセスがないと失敗します。
MCPコンテナ — 実行中で正常であることを確認してください。
LatenceTech APIコンテナ — 実行中で正常であることを確認してください。

lti_analyzerディレクトリから関連するコンテナの状態を確認します：

docker ps
docker logs lti_analyzer_latencetech_mcp_1
docker logs lti_analyzer_latencetech_api_1

コンテナが停止している場合は再起動します：

docker compose up -d

コンテナが実行中でもチャットボットが失敗する場合は、アナライザーホストに送信インターネットアクセスがあることを確認してください：

curl -s https://api.openai.com

レポートが生成されない

レポート機能もOpenAIを使用します。アナライザーホストに送信インターネットアクセスがない場合、レポート生成は失敗します。同じ方法で接続性を確認してください：

curl -s https://api.openai.com

アナライザーのアップグレード

アナライザーの新しいバージョンをインストールする前に、非互換性を避けるために前のインストールからダウンロードおよび生成されたファイルを削除する必要があります。各バージョンを別のディレクトリにインストールすることをお勧めします。