IoT Edge デバイスのトラブルシューティング
適用対象:
IoT Edge 1.5 IoT Edge 1.4
重要
サポートされているリリースは、IoT Edge 1.5 LTS と IoT Edge 1.4 LTS です。 IoT Edge 1.4 LTS は、2024 年 11 月 12 日にサポートが終了します。 以前のリリースの場合は、「IoT Edge を更新する」を参照してください。
お使いの環境で Azure IoT Edge の実行中に問題が発生した場合は、この記事を参考にしてトラブルシューティングと診断を行ってください。
"check" コマンドを実行する
IoT Edge のトラブルシューティング時の最初のステップは、check コマンドを使用することです。このコマンドは、一般的な問題の構成の収集と接続テストを実行します。 check コマンドは、リリース 1.0.7 以降で使用できます。
Note
トラブルシューティング ツールでは、IoT Edge デバイスがプロキシ サーバーの背後にある場合、接続チェックを実行できません。
check コマンドは次のように実行できます。または、--help フラグを追加してオプションの完全なリストを表示できます。
sudo iotedge check
トラブルシューティング ツールでは、次の 3 つのカテゴリに分類される多くのチェックが実行されます。
- "構成検査" では、構成ファイルおよびコンテナー エンジンの問題を含め、IoT Edge デバイスからクラウドへの接続を妨げるおそれのある問題の詳細を調べます。
- "接続検査" では、IoT Edge ランタイムがホスト デバイス上のポートにアクセス可能であること、およびすべての IoT Edge コンポーネントが IoT Hub にアクセス可能であることが確認されます。 IoT Edge デバイスがプロキシの背後にある場合、この一連の検査でてエラーが返されます。
- "製品の準備完了検査" では、デバイス証明機関 (CA) の証明書の状態やモジュール ログ ファイルの構成など、推奨される運用上のベスト プラクティスが検査されます。
IoT Edge チェック ツールでは、コンテナーを使用して診断が実行されます。 コンテナー イメージ mcr.microsoft.com/azureiotedge-diagnostics:latest は、Microsoft Container Registry から入手できます。 インターネットに直接アクセスせずにデバイスのチェックを実行する必要がある場合は、デバイスにコンテナー イメージへのアクセス権が必要です。
入れ子になった IoT Edge デバイスを使用するシナリオでは、親デバイスを経由してイメージのプルをルーティングすることで、ダウンストリーム デバイスの診断イメージにアクセスできます。
sudo iotedge check --diagnostics-image-name <parent_device_fqdn_or_ip>:<port_for_api_proxy_module>/azureiotedge-diagnostics:1.2
エラーや警告が表示された場合の対処方法など、このツールが実行する各診断チェックの詳細については、IoT Edge のトラブルシューティング チェックに関するページを参照してください。
"support-bundle" コマンドを使用してデバッグ情報を収集する
IoT Edge デバイスからログを収集する必要がある場合、最も便利な方法は support-bundle コマンドを使用することです。 このコマンドを使うと、既定では、モジュールと IoT Edge Security Manager とコンテナー エンジンのログ、iotedge check の JSON 出力、および他の有用なデバッグ情報が収集されます。 共有しやすいように、それらが 1 つのファイルに圧縮されます。 support-bundle コマンドは、リリース 1.0.9 以降で使用できます。
ログを取得する過去の期間を指定するには、--since フラグを指定して support-bundle コマンドを実行します。 たとえば、6h では過去 6 時間、6d では過去 6 日間、6m では過去 6 分間のログが取得されます。 オプションの完全な一覧を表示するには、--help フラグを含めます。
sudo iotedge support-bundle --since 6h
既定では、 support-bundle コマンドにより、コマンドが呼び出されるディレクトリに support_bundle.zip という名前の zip ファイルが作成されます。 出力に別のパスまたはファイル名を指定するには、フラグ --output を使用します。
コマンドの詳細については、ヘルプ情報を参照してください。
iotedge support-bundle --help
また、組み込みのダイレクト メソッド呼び出し UploadSupportBundle を使用して、support-bundle コマンドの出力を Azure Blob Storage にアップロードすることもできます。
警告
support-bundle コマンドからの出力には、ホスト、デバイス名とモジュール名、モジュールによってログに記録された情報などが含まれる場合があります。パブリック フォーラムで出力を共有する場合は、この点に注意してください。
ランタイムから収集されたメトリックを確認する
IoT Edge ランタイム モジュールでは、IoT エッジ デバイスの正常性を監視して把握するのに役立つメトリックが生成されます。 監視しやすくするために、metrics-collector モジュールをデプロイに追加して、これらのメトリックの収集とクラウドへの送信を処理します。
詳細については、「メトリックの収集と転送」を参照してください。
IoT Edge のバージョンを確認する
古いバージョンの IoT Edge を実行している場合は、アップグレードすると問題が解決されることがあります。 iotedge check ツールでは、IoT Edge セキュリティ デーモンが最新バージョンであるかを確認しますが、IoT Edge ハブとエージェント モジュールのバージョンは確認しません。 デバイス上のランタイム モジュールのバージョンを確認するには、iotedge logs edgeAgent と iotedge logs edgeHub のコマンドを使用します。 バージョン番号は、モジュールの起動時にログで宣言されます。
デバイスを更新する手順については、「IoT Edge セキュリティ デーモンおよびランタイムの更新」を参照してください。
デバイスに IoT Edge がインストールされていることを確認する
edgeAgent モジュール ツインの監視によって、デバイスに IoT Edge がインストールされていることを確認できます。
最新の edgeAgent モジュール ツインを取得するには、Azure Cloud Shell から次のコマンドを実行します。
az iot hub module-twin show --device-id <edge_device_id> --module-id '$edgeAgent' --hub-name <iot_hub_name>
このコマンドは、edgeAgent の報告されるプロパティすべてを出力します。 次に、デバイスの状態を監視する便利な方法を示します。
- ランタイムの状態
- ランタイムの開始時刻
- ランタイムの最後の終了時刻
- ランタイムの再起動回数
IoT Edge Security Manager の状態とそのログを確認する
IoT Edge Security Manager は、デバイスの起動時およびプロビジョニングでの IoT Edge システムの初期化などの操作を担当します。 IoT Edge が開始されていない場合、セキュリティ マネージャーのログに有用な情報が提供されることがあります。
IoT Edge システム サービスの状態を表示します。
sudo iotedge system statusIoT Edge システム サービスのログを表示します。
sudo iotedge system logs -- -fデバッグレベルのログを有効にして、IoT Edge システム サービスのより詳細なログを表示します。
デバッグレベルのログを有効にします。
sudo iotedge system set-log-level debug sudo iotedge system restartデバッグ後に既定の情報レベルのログに戻ります。
sudo iotedge system set-log-level info sudo iotedge system restart
コンテナーのログで問題を確認する
IoT Edge セキュリティ デーモンが実行されている場合は、コンテナーのログを参照して問題を検出します。 デプロイされたコンテナーから開始して、IoT Edge ランタイムを形成しているコンテナーである edgeAgent および edgeHub を確認します。 通常、IoT Edge エージェントのログでは、各コンテナーのライフサイクルについての情報が提供されます。 IoT Edge ハブのログでは、メッセージングとルーティングについての情報が提供されます。
コンテナーのログは、いくつかの場所から取得できます。
IoT Edge デバイスで、次のコマンドを実行してログを表示します。
iotedge logs <container name>Azure portal では、組み込みのトラブルシューティング ツールを使用します。 Azure portal から IoT Edge デバイスを監視しトラブルシューティングを行う
Uploadmodulelogs ダイレクトメソッドを使用して、モジュールのログを Azure Blob Storage にアップロードします。
コンテナー ログをクリーンナップする
既定では、Moby コンテナー エンジンは、コンテナー ログ サイズに制限を設定しません。 時間の経過と共に、大量のログのため、デバイスがログでいっぱいになり、ディスク容量が不足する可能性があります。 大きなコンテナー ログが IoT Edge デバイスのパフォーマンスに影響を与える場合は、次のコマンドを使用して、コンテナーとそれに関連するログを強制的に削除します。
引き続きトラブルシューティングを行う場合は、コンテナー ログを検査してからこの手順を実行します。
警告
未配信メッセージ バックログがあり、 ホスト ストレージ がセットアップされていないときに edgeHub コンテナーを強制的に削除すると、配信されていないメッセージは失われます。
docker rm --force <container name>
進行中のログのメンテナンスと運用のシナリオでは、既定のログ ドライバーを設定します。
IoT Edge ハブを通過するメッセージを表示する
IoT Edge ハブを通過するメッセージを表示し、ランタイム コンテナーから得た詳細なログから分析情報を収集できます。 これらのコンテナーで詳細ログを有効にするには、配置マニフェストで環境変数 RuntimeLogLevel を設定します。
IoT Edge ハブを経由するメッセージを表示するには、edgeHub モジュールの環境変数 RuntimeLogLevel を debug に設定します。
edgeHub と edgeAgent の両方のモジュールにこのランタイム ログ環境変数があり、既定値は info に設定されています。 この環境変数は、次の値を取ることができます。
- fatal
- エラー
- warning
- info
- debug
- verbose
IoT Hub デバイスと IoT デバイスの間で送信されたメッセージを確認することもできます。 Visual Studio Code 用の Azure IoT Hub 拡張機能を使用して、これらのメッセージを表示します。 詳細については、Azure IoT で開発するときの便利なツールに関するページを参照してください。
コンテナーを再起動する
ログとメッセージの情報を調べた後は、コンテナーの再起動を試みることもできます。
IoT Edge デバイスで、次のコマンドを使用してモジュールを再起動します。
iotedge restart <container name>
IoT Edge ランタイム コンテナーを再起動する:
iotedge restart edgeAgent && iotedge restart edgeHub
Azure portal からリモートでモジュールを再起動することもできます。 詳細については、「Azure portal から IoT Edge デバイスを監視およびトラブルシューティングする」を参照してください。
ファイアウォール規則とポート構成規則を確認する
Azure IoT Edge では、サポートされている IoT Hub プロトコルを使用した、オンプレミス サーバーから Azure クラウドへの通信が許可されています。 詳細については、通信プロトコルの選択に関するページを参照してください。 セキュリティ強化のため、Azure IoT Edge と Azure IoT Hub の間の通信チャネルは常にアウトバウンドに構成されます。 この構成は、サービス支援通信方式に基づいていて、悪意のあるエンティティが探る攻撃対象の領域が最小限になります。 インバウンド通信が必要なのは、Azure IoT Hub がメッセージを Azure IoT Edge デバイスにプッシュする必要がある特定のシナリオのみです。 cloud-to-device メッセージは、セキュリティで保護された TLS チャネルを使用して保護されます。また、X.509 証明書と TPM デバイス モジュールを使用してさらに保護することができます。 この通信の確立方法は、Azure IoT Edge セキュリティ マネージャーによって管理されます。IoT Edge セキュリティ マネージャーに関するページを参照してください。
IoT Edge は、Azure IoT Edge ランタイムとデプロイされたモジュールをセキュリティで保護するための強化された構成を提供しますが、依然として基盤になるマシンとネットワークの構成に依存します。 そのため、エッジからクラウドへの安全な通信を実現するための適切なネットワーク規則およびファイアウォール規則が設定されていることを確認することが不可欠です。 Azure IoT Edge ランタイムがホストされている、基になるサーバー用にファイアウォール規則を構成するときには、以下の表をガイドラインとして使用できます。
| プロトコル | [ポート] | 着信 | 送信 | ガイダンス |
|---|---|---|---|---|
| MQTT | 8883 | ブロック (既定値) | ブロック (既定値) |
|
| AMQP | 5671 | ブロック (既定値) | オープン (既定値) |
|
| HTTPS | 443 | ブロック (既定値) | オープン (既定値) |
|
最終手段: すべてのコンテナーを停止して再作成する
場合によっては、既存のネットワークまたはオペレーティング システムの制約に対処するために、システムに大幅で特別な変更が必要になることがあります。 たとえば、システムでデータ ディスク マウントやプロキシの設定の変更が必要になることがあります。 これまでの手順をすべて試してもコンテナー エラーが発生する場合は、Docker システムのキャッシュまたは永続的なネットワーク設定が最新の再構成で更新されていない可能性があります。 この場合の最終手段は、docker prune を使用して最初からやり直すことです。
以下のコマンドは、IoT Edge システム (およびすべてのコンテナー) を停止し、docker prune に "all" および "volume" オプションを使用してすべてのコンテナーとボリュームを削除します。 コマンドが発行する警告を確認し、準備ができたら y で確認します。
sudo iotedge system stop
docker system prune --all --volumes
WARNING! This will remove:
- all stopped containers
- all networks not used by at least one container
- all volumes not used by at least one container
- all images without at least one container associated to them
- all build cache
Are you sure you want to continue? [y/N]
システムを再び起動します。 安全のため、残っている可能性がある構成の適用とシステムの起動を 1 つのコマンドで行います。
sudo iotedge config apply
数分待ってからもう一度確認します。
sudo iotedge list
次のステップ
IoT Edge プラットフォームのバグを発見したと思われる場合は、 改善を続けられるように問題を報告してください。
その他に質問がある場合は、サポート リクエストを作成して対応を要請してください。