分散トレース (プレビュー) を使用して Azure IoT の cloud-to-device メッセージをトレースする

[アーティクル]
03/10/2024

IoT Hub で分散トレース (プレビュー) を使って、Azure サービスを通過する IoT メッセージを監視します。 IoT Hub は、分散トレースをサポートする最初の Azure サービスの 1 つです。多くの Azure サービスが分散トレースをサポートしているため、ソリューションに関連する Azure サービス全体でモノのインターネット (IoT) メッセージをトレースできます。この機能の詳細については、分散トレースの概要に関する記事を参照してください。

IoT Hub の分散トレースを有効にすると、次の操作を行えるようになります。

トレースコンテキストを使って、IoT Hub を介した各メッセージの流れを監視できます。トレースコンテキストには、あるコンポーネントからのイベントを別のコンポーネントからのイベントに関連付けることができる関連付け ID が含まれています。デバイスツインを使用して、サブセットまたはすべての IoT デバイスメッセージに適用できます。
トレースコンテキストを自動的に Azure Monitor ログに記録できます。
デバイスから IoT Hub およびルーティングエンドポイントまでのメッセージフローと待ち時間を測定および把握できます。

重要

Azure IoT ハブの分散トレースは現在プレビュー段階です。ベータ版、プレビュー版、または一般提供としてまだリリースされていない Azure の機能に適用される法律条項については、「Microsoft Azure プレビューの追加使用条件」を参照してください。

前提条件

次のいずれかのリージョンで作成された Azure IoT ハブ。
- 北ヨーロッパ
- 東南アジア
- 米国西部 2
お使いの IoT ハブに登録されているデバイス。 IoT ハブにデバイスがない場合は、「デバイスの登録」の手順のようにして、この記事で使うデバイス接続文字列を保存します。
この記事は、読者が IoT Hub へのテレメトリメッセージの送信について理解していることを前提としています。
最新バージョンの Git。

パブリックプレビューの制限と考慮事項

このプレビュー機能が実際のシナリオに適しているかどうかを判断するには、次の制限事項を考慮してください。

W3C トレースコンテキスト標準の提案は、現在、草案の段階です。
クライアント SDK が現在サポートしている開発言語は C のみです (Azure IoT device SDK for C のパブリックプレビューブランチにあります)。
cloud-to-device のツイン機能は、IoT Hub の基本層では使用できません。ただし、IoT Hub では、適切に構成されたトレースコンテキストヘッダーを認識した場合には、Azure Monitor にログを記録します。
効率的な操作を確実にするために、IoT Hub は、分散トレースの一部として発生する可能性のあるログ記録のレートにスロットルを適用します。
分散トレース機能は、次のリージョンで作成された IoT ハブでのみサポートされています。
- 北ヨーロッパ
- 東南アジア
- 米国西部 2

Azure IoT 分散トレースを理解する

Azure IoT 参照アーキテクチャを含む多くの IoT ソリューションは、通常、マイクロサービスアーキテクチャのバリアントに準拠しています。 IoT ソリューションが複雑になるにつれて、数多くのマイクロサービスを使用することになります。これらのマイクロサービスは、Azure のマイクロサービスのものである場合とそうでない場合があります。

IoT メッセージのドロップまたはスローダウンが発生している場所を正確に特定することは困難である可能性があります。たとえば、5 つの異なる Azure サービスと 1,500 台のアクティブデバイスを使用する IoT ソリューションがあるとします。 device-to-cloud メッセージがデバイスごとに毎秒 10 件 (合計で毎秒 15,000 件) 送信されます。ただし、Web アプリには毎秒 10,000 件のメッセージしか表示されません。どのようにして原因を見つけることができるのでしょうか。

サービス間での IoT メッセージのフローを再構築するには、各サービスで、メッセージを一意に識別する関連付け ID を伝達する必要があります。 Azure Monitor が一元管理されたシステムで関連付け ID を収集すると、それらの ID を使用してメッセージのフローを確認できます。この方法は、分散トレースパターンと呼ばれます。

Microsoft は、分散トレースのより広範な採用をサポートするために、分散トレースの W3C 標準の提案に寄与しています。 IoT Hub の分散トレースのサポートが有効な場合、生成されたメッセージごとに次のフローに従います。

IoT デバイスでメッセージが生成されます。
IoT デバイスでは、このメッセージにトレースコンテキストを割り当てる必要があるかを (クラウドからサポートを受けて) 判断します。
SDK によって、メッセージ作成タイムスタンプを格納する tracestate 値がメッセージプロパティに追加されます。
IoT デバイスによって、IoT Hub にメッセージが送信されます。
メッセージが IoT Hub ゲートウェイに到着します。
IoT Hub で、メッセージプロパティ内の tracestate 値が調べられ、それが正しい形式であるかどうか確認されます。その場合、IoT Hub によって、メッセージのグローバルに一意の trace-id 値、および "ホップ" の場合は span-id 値が生成されます。IoT Hub では、これらの値が DiagnosticIoTHubD2C 操作で IoT Hub 分散トレースログに記録されます。
メッセージの処理が終了すると、IoT Hub によって別の span-id 値が生成され、DiagnosticIoTHubIngress の操作で既存の trace-id 値とともにそれが記録されます。
メッセージに対してルーティングが有効になっている場合、IoT Hub はそれをカスタムエンドポイントに書き込みます。 IoT Hub では、同じ trace-id 値を持つ別の span-id 値を DiagnosticIoTHubEgress カテゴリに記録します。

IoT ハブで分散トレースを構成する

このセクションでは、分散トレース属性 (関連付け ID とタイムスタンプ) を記録するように IoT ハブを構成します。

Azure portal で、IoT ハブに移動します。
IoT ハブの左側のウィンドウで、下にスクロールして [監視] セクションを表示し、[診断設定] を選択します。
[診断設定の追加] を選択します。
[診断設定の名前] ボックスに、新しい診断設定の名前を入力します。たとえば、「DistributedTracingSettings」と入力します。
ログ情報の送信先を決定するために、[宛先の詳細] の下にある次のオプションから 1 つ以上を選択します。
- [ストレージアカウントへのアーカイブ] :ログ情報を格納するようにストレージアカウントを構成します。
- [イベントハブへのストリーム] :ログ情報を格納するようにイベントハブを構成します。
- [Log Analytics への送信]: ログ情報を格納するようにログ分析ワークスペースを構成します。
[ログ] セクションで、ログに記録する操作を選択します。

[分散トレース] を含め、ログを保持する日数に対して [リテンション] 期間を構成します。ログのリテンション期間は、ストレージのコストに影響します。
[保存] を選択します。
(省略可能) 異なる場所へのメッセージフローを確認するために、2 つ以上の異なるエンドポイントへのルーティング規則を設定します。

ログ記録を有効にすると、次の状況のいずれかで有効なトレースプロパティを含むメッセージが検出されたときに、IoT Hub によってログが記録されます。

メッセージが IoT ハブのゲートウェイに到着する。
IoT ハブがメッセージを処理する。
メッセージがカスタムエンドポイントにルーティングされる。ルーティングを有効にする必要があります。

これらのログとそのスキーマの詳細については、IoT Hub の監視と IoT Hub リソースログの分散トレースに関する記事を参照してください。

サンプリングオプションを更新する

クラウドからトレースするメッセージの割合を変更するには、デバイスツインを更新する必要があります。更新するには、Azure portal または IoT Hub サービス SDK の JSON エディターを使用します。次のサブセクションで例を示します。

1 つのデバイスを更新する

Azure portal または Visual Studio Code 用 Azure IoT Hub 拡張機能 (VS Code) を使って、1 台のデバイスのサンプリングレートを更新できます。

Azure Portal
VS Code

Azure portal で IoT ハブに移動し、メニューの [デバイス管理] セクションから [デバイス] を選びます。
デバイスを選択します。
[分散トレース (プレビュー)] で、歯車アイコンを選びます。開いたパネルで、次の操作を行います。
1. [有効化] オプションをオンにします。
2. [サンプリングレート] で、0 から 100 の割合を選択します。
3. [保存] を選択します。
数秒待ってから [最新の情報に更新] を選択します。デバイスが変更を正常に認識すると、チェックマークが付いた同期アイコンが表示されます。

複数のデバイスを一括更新する

複数のデバイスの分散トレースサンプリング構成を更新するには、自動デバイス構成を使用します。次のツインスキーマに従います。

{
    "properties": {
        "desired": {
            "azureiot*com^dtracing^1": {
                "sampling_mode": 1,
                "sampling_rate": 100
            }
        }
    }
}

要素名	必須	タイプ	説明
`sampling_mode`	はい	Integer	サンプリングのオンとオフを切り替えるために、現在 2 つのモード値がサポートされています。 `1` がオンで、`2` がオフです。
`sampling_rate`	はい	Integer	この値は、パーセンテージです。 `0` から `100` までの値 (両端を含む) のみ許可されます。

トレースのクエリと視覚化

IoT ハブによってログされたすべてのトレースを表示するには、診断設定で選んだログストアに対してクエリを実行します。このセクションでは、Log Analytics を使用してクエリを実行する方法について説明します。

リソースログを使って Log Analytics を設定した場合、DistributedTracing カテゴリでログを探すことでクエリを実行します。たとえば、次のクエリでは、記録されたすべてのトレースが表示されます。

// All distributed traces 
AzureDiagnostics 
| where Category == "DistributedTracing" 
| project TimeGenerated, Category, OperationName, Level, CorrelationId, DurationMs, properties_s 
| order by TimeGenerated asc

Log Analytics のログの例をいくつか次に示します。

生成時刻	操作の名前	カテゴリ	Level	関連付け ID	実行時間 (ミリ秒)	Properties
2018-02-22T03:28:28.633Z	DiagnosticIoTHubD2C	DistributedTracing	Informational	00-8cd869a412459a25f5b4f31311223344-0144d2590aacd909-01		`{"deviceId":"AZ3166","messageSize":"96","callerLocalTimeUtc":"2018-02-22T03:27:28.633Z","calleeLocalTimeUtc":"2018-02-22T03:27:28.687Z"}`
2018-02-22T03:28:38.633Z	DiagnosticIoTHubIngress	DistributedTracing	Informational	00-8cd869a412459a25f5b4f31311223344-349810a9bbd28730-01	20	`{"isRoutingEnabled":"false","parentSpanId":"0144d2590aacd909"}`
2018-02-22T03:28:48.633Z	DiagnosticIoTHubEgress	DistributedTracing	Informational	00-8cd869a412459a25f5b4f31311223344-349810a9bbd28730-01	23	`{"endpointType":"EventHub","endpointName":"myEventHub", "parentSpanId":"0144d2590aacd909"}`

ログの種類については、Azure IoT Hub の分散トレースログに関する記事を参照してください。

サンプルアプリケーションを実行する

このセクションでは、Azure IoT C SDK で使用する開発環境を準備します。次に、サンプルの 1 つを変更して、デバイスのテレメトリメッセージに対して分散トレースを有効にします。

これらの手順は、Windows でサンプルを構築するためのものです。その他の環境では、C SDK のコンパイルに関するページ、またはプラットフォーム固有の開発用のパッケージ済み C SDK に関するページを参照してください。

ソースコードを複製し、初期化する

Visual Studio 2022 用の C++ によるデスクトップ開発ワークロードをインストールします。 Visual Studio 2019 もサポートされます。
CMake をインストールします。コマンドプロンプトで cmake -version を入力し、これが PATH に含まれていることを確認します。
コマンドプロンプトまたは Git Bash シェルを開きます。次のコマンドを実行して、Azure IoT C SDK GitHub リポジトリのパブリックプレビューブランチの最新リリースをクローンします。
```
git clone -b public-preview https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c
git submodule update --init
```
この操作が完了するまで数分かかることが予想されます。
azure-iot-sdk-c ディレクトリから次のコマンドを実行して cmake サブディレクトリを作成し、cmake フォルダーに移動します。
```
mkdir cmake
cd cmake
cmake ..
```
CMake で C++ コンパイラが見つからない場合は、上記のコマンドの実行中にビルドエラーが発生している可能性があります。これが発生した場合は、Visual Studio コマンドプロンプトでコマンドを実行してください。

ビルドが成功すると、最後のいくつかの出力行は次のようになります。
```
$ cmake ..
-- Building for: Visual Studio 15 2017
-- Selecting Windows SDK version 10.0.16299.0 to target Windows 10.0.17134.
-- The C compiler identification is MSVC 19.12.25835.0
-- The CXX compiler identification is MSVC 19.12.25835.0

...

-- Configuring done
-- Generating done
-- Build files have been written to: E:/IoT Testing/azure-iot-sdk-c/cmake
```

テレメトリサンプルを編集して分散トレースを有効にする

このセクションでは、SDK リポジトリ内の iothub_ll_telemetry_sample.c サンプルを編集して、分散トレースを有効にします。また、編集されたバージョンのサンプルを azure-iot-distributed-tracing-sample リポジトリからコピーすることもできます。

エディターを使用して、azure-iot-sdk-c/iothub_client/samples/iothub_ll_telemetry_sample/iothub_ll_telemetry_sample.c ソースファイルを開きます。
次の connectionString 定数の宣言を探します。
```
/* Paste in the your iothub connection string  */
static const char* connectionString = "[device connection string]";
#define MESSAGE_COUNT        5000
static bool g_continueRunning = true;
static size_t g_message_count_send_confirmations = 0;
```
connectionString 定数の値を、送信テレメトリのクイックスタートの「デバイスの登録」セクションで保存したデバイス接続文字列に置き換えます。
IoTHubDeviceClient_LL_SetConnectionStatusCallback を呼び出しているコード行を見つけ、送信メッセージのループ前に接続状態のコールバック関数を登録します。その行の下にコードを追加して IoTHubDeviceClient_LL_EnablePolicyConfiguration を呼び出し、デバイスの分散トレースを有効にします。
```
// Setting connection status callback to get indication of connection to iothub
(void)IoTHubDeviceClient_LL_SetConnectionStatusCallback(device_ll_handle, connection_status_callback, NULL);

// Enabled the distrubted tracing policy for the device
(void)IoTHubDeviceClient_LL_EnablePolicyConfiguration(device_ll_handle, POLICY_CONFIGURATION_DISTRIBUTED_TRACING, true);

do
{
    if (messages_sent < MESSAGE_COUNT)
```
IoTHubDeviceClient_LL_EnablePolicyConfiguration 関数により、デバイスツインを介して構成される特定の IoT Hub 機能のポリシーが有効になります。追加のコード行を使用することで POLICY_CONFIGURATION_DISTRIBUTED_TRACING が有効になると、デバイスのトレース動作は、デバイスツインで行われた分散トレースの変更を反映します。

すべてのクォータを使い尽くさずにサンプルアプリを実行し続けるために、送信メッセージループの末尾に 1 秒の遅延を追加します。

    else if (g_message_count_send_confirmations >= MESSAGE_COUNT)
    {
        // After all messages are all received stop running
        g_continueRunning = false;
    }

    IoTHubDeviceClient_LL_DoWork(device_ll_handle);
    ThreadAPI_Sleep(1000);

} while (g_continueRunning);

コンパイルと実行

前に作成した CMake ディレクトリ (azure-iot-sdk-c/cmake) から iothub_ll_telemetry_sample プロジェクトディレクトリに移動し、サンプルをコンパイルします。
```
cd iothub_client/samples/iothub_ll_telemetry_sample
cmake --build . --target iothub_ll_telemetry_sample --config Debug
```
アプリケーションを実行します。デバイスにより、分散トレースをサポートするテレメトリが送信されます。
```
Debug/iothub_ll_telemetry_sample.exe
```
そのままアプリを実行します。コンソールウィンドウで、IoT Hub に送信されるメッセージを確認できます。

クラウドからサンプリング決定を受信できるクライアントアプリの場合は、分散トレースサンプルリポジトリにある iothub_devicetwin_sample.c サンプルを試してください。

Microsoft 以外のクライアントの回避策

C SDK を使用せずに分散トレース機能を実装する方が複雑です。それは推奨されません。

最初に、開発者ガイド「IoT Hub メッセージを作成し、読み取る」に従って、すべての IoT Hub プロトコルプリミティブをご自身のメッセージで実装する必要があります。次に、MQTT および AMQP メッセージのプロトコルプロパティを編集して、tracestate をシステムプロパティとして追加します。

具体的な内容は次のとおりです。

MQTT の場合は、%24.tracestate=timestamp%3d1539243209 をメッセージトピックに追加します。 1539243209 は、Unix タイムスタンプ形式のメッセージ作成時に置き換える必要があります。例としては、C SDK の実装を参照してください。
AMQP の場合は、key("tracestate") と value("timestamp=1539243209") をメッセージの注釈として追加します。参照実装については、uamqp_messaging.c ファイルを参照してください。

このプロパティを含むメッセージの割合を制御するには、ツインの更新など、クラウドによって開始されたイベントをリッスンするロジックを実装します。

次のステップ

マイクロサービスの一般的な分散トレースパターンについて詳しくは、マイクロサービスアーキテクチャパターン: 分散トレースに関するページを参照してください。

次の方法で共有

分散トレース (プレビュー) を使用して Azure IoT の cloud-to-device メッセージをトレースする

前提条件

パブリックプレビューの制限と考慮事項

Azure IoT 分散トレースを理解する

IoT ハブで分散トレースを構成する

サンプリングオプションを更新する

1 つのデバイスを更新する

複数のデバイスを一括更新する

トレースのクエリと視覚化

サンプルアプリケーションを実行する

ソースコードを複製し、初期化する

テレメトリサンプルを編集して分散トレースを有効にする

コンパイルと実行

Microsoft 以外のクライアントの回避策

次のステップ

フィードバック

その他のリソース

次の方法で共有

分散トレース (プレビュー) を使用して Azure IoT の cloud-to-device メッセージをトレースする

前提条件

パブリック プレビューの制限と考慮事項

Azure IoT 分散トレースを理解する

IoT ハブで分散トレースを構成する

サンプリング オプションを更新する

1 つのデバイスを更新する

複数のデバイスを一括更新する

トレースのクエリと視覚化

サンプル アプリケーションを実行する

ソース コードを複製し、初期化する

テレメトリ サンプルを編集して分散トレースを有効にする

コンパイルと実行

Microsoft 以外のクライアントの回避策

次のステップ

フィードバック

その他のリソース

パブリックプレビューの制限と考慮事項

サンプリングオプションを更新する

サンプルアプリケーションを実行する

ソースコードを複製し、初期化する

テレメトリサンプルを編集して分散トレースを有効にする