使用分散式追蹤來追蹤 Azure IoT 裝置到雲端訊息 （預覽）
在 IoT 中樞 中使用分散式追蹤（預覽版）來監視透過 Azure 服務傳遞的 IoT 訊息。 IoT 中樞 是第一個支持分散式追蹤的 Azure 服務之一。 隨著更多 Azure 服務支援分散式追蹤，您可以追蹤整個參與解決方案的 Azure 服務中的物聯網 （IoT） 訊息。 如需此功能的詳細資訊，請參閱 什麼是分散式追蹤？。
當您啟用 IoT 中樞 的分散式追蹤時，您可以：
- 使用追蹤內容透過 IoT 中樞監視每個訊息的流程。 追蹤內容包含相互關聯標識碼，可讓您將某個元件的事件與另一個元件的事件相互關聯。 您可以使用裝置對應項，將它套用至子集或所有IoT裝置訊息。
- 將追蹤內容記錄至 Azure 監視器記錄。
- 測量並瞭解從裝置到 IoT 中樞和路由端點的訊息流程和延遲。
重要
分散式追蹤 Azure IoT 中樞 目前處於預覽狀態。 請參閱 Microsoft Azure 預覽版增補使用規定，以了解適用於 Azure 功能 (搶鮮版 (Beta)、預覽版，或尚未正式發行的版本) 的法律條款。
必要條件
在下列其中一個區域中建立的 Azure IoT 中樞。
- 北歐
- 東南亞
- 美國西部 2
已註冊至IoT中樞的裝置。 如果您沒有裝置，請遵循在IoT中樞註冊新裝置中的步驟，並將裝置儲存 連接字串 以用於本文。
本文假設您已熟悉將遙測訊息傳送至 IoT 中樞。
最新版的 Git。
公開預覽限制和考慮
請考慮下列限制，以判斷此預覽功能是否適合您的案例：
W3C 追蹤內容標準的建議目前是工作草稿。
用戶端 SDK 目前支援的唯一開發語言是 C，在 適用於 C 的 Azure IoT 裝置 SDK 公開預覽分支中
雲端到裝置對應項功能不適用於 IoT 中樞 基本層。 不過，如果 Azure 監視器看到正確撰寫的追蹤內容標頭，IoT 中樞 仍會記錄至 Azure 監視器。
為了確保有效率的作業，IoT 中樞 會對在分散式追蹤中發生的記錄速率施加節流。
分散式追蹤功能僅支援在下列區域中建立的IoT中樞：
- 北歐
- 東南亞
- 美國西部 2
瞭解 Azure IoT 分散式追蹤
許多IoT解決方案，包括 Azure IoT 參考架構，通常會遵循微服務架構的變體。 當IoT解決方案變得更複雜時，您最終會使用十幾個或更多微服務。 這些微服務可能或可能不是來自 Azure。
找出IoT訊息捨棄或速度變慢的位置可能具有挑戰性。 例如，假設您有一個IoT解決方案，其使用五個不同的 Azure 服務和 1,500 個作用中裝置。 每個裝置每秒傳送 10 個裝置到雲端訊息，每秒共傳送 15,000 則訊息。 但您注意到 Web 應用程式每秒只會看到 10,000 則訊息。 如何找到罪魁禍首？
為了讓您重新建構跨服務的IoT訊息流程，每個服務都應該傳播可唯一 識別訊息的相互關聯標識碼 。 在 Azure 監視器在集中式系統中收集相互關聯標識碼之後，您可以使用這些識別碼來查看訊息流程。 此方法稱為 分散式追蹤模式。
為了支援更廣泛的分散式追蹤採用，Microsoft 正在 為分散式追蹤提供 W3C 標準提案。 啟用 IoT 中樞 的分散式追蹤支援時，它會針對每個產生的訊息遵循此流程：
- IoT 裝置上會產生訊息。
- IoT 裝置會決定此訊息應該使用追蹤內容來指派。
- SDK 會將值新增
tracestate至 message 屬性，其中包含訊息建立的時間戳。 - IoT 裝置會將訊息傳送至 IoT 中樞。
- 訊息會抵達 IoT 中樞閘道。
- IoT 中樞 尋找
tracestate訊息屬性中的值，並檢查其格式是否正確。 如果是，IoT 中樞 會產生訊息的全域唯trace-id一值，併span-id產生 「hop」 的值。IoT 中樞 記錄作業下 IoT 中樞 分散式追蹤記錄中的DiagnosticIoTHubD2C這些值。 - 當訊息處理完成時，IoT 中樞 會產生另一個
span-id值，並在作業底下DiagnosticIoTHubIngress記錄它以及現有的trace-id值。 - 如果訊息已啟用路由，IoT 中樞 將它寫入自定義端點。 IoT 中樞 記錄另一個
span-id在類別下DiagnosticIoTHubEgress具有相同trace-id值的值。
在IoT中樞中設定分散式追蹤
在本節中，您會設定IoT中樞來記錄分散式追蹤屬性（相互關聯標識符和時間戳）。
移至 Azure 入口網站 中的IoT中樞。
在 IoT 中樞的左窗格中，向下捲動至 [監視] 區段，然後選取 [ 診斷設定]。
選取 [新增診斷設定]。
在 [ 診斷設定名稱 ] 方塊中，輸入新診斷設定的名稱。 例如，輸入 DistributedTracing 設定。
在 [目的地詳細數據] 底下，選擇下列一或多個選項，以判斷傳送記錄資訊的位置：
- 封存至記憶體帳戶：設定記憶體帳戶以包含記錄資訊。
- 串流至事件中樞：設定事件中樞以包含記錄資訊。
- 傳送至 Log Analytics：設定 Log Analytics 工作區以包含記錄資訊。
在 [ 記錄] 區段中，選取您要記錄的作業。
包含分散式追蹤，並設定保留期間，以保留多少天記錄。 記錄保留會影響記憶體成本。
選取 [儲存]。
（選擇性）若要查看訊息流向不同位置，請將路由規則設定 為至少兩個不同的端點。
開啟記錄之後，IoT 中樞 在下列任何情況下遇到包含有效追蹤屬性的訊息時記錄記錄：
- 訊息會抵達IoT中樞的閘道。
- IoT 中樞會處理訊息。
- 訊息會路由傳送至自定義端點。 必須啟用路由。
若要深入瞭解這些記錄及其架構，請參閱在 IoT 中樞 資源記錄中監視 IoT 中樞 和分散式追蹤。
更新取樣選項
若要變更要從雲端追蹤的訊息百分比，您必須更新裝置對應項。 您可以使用 Azure 入口網站 或 IoT 中樞 服務 SDK 中的 JSON 編輯器進行更新。 下列小節提供範例。
更新單一裝置
您可以使用 Visual Studio Code 的 Azure 入口網站 或 Azure IoT 中樞 擴充功能來更新單一裝置的取樣率。
移至 Azure 入口網站 中的IoT中樞，然後從功能表的 [裝置管理] 區段中選取 [裝置]。
選擇您的裝置。
選取 [分散式追蹤] 底下的齒輪圖示（預覽）。 開啟面板中：
- 選取 [ 啟用] 選項。
- 針對 [取樣率]，選擇介於 0 到 100 之間的百分比。
- 選取 [儲存]。
等候幾秒鐘，然後選取 [ 重新整理]。 如果裝置成功認可您的變更，就會顯示具有複選標記的同步圖示。
大量更新多個裝置
若要更新多個裝置的分散式追蹤取樣組態，請使用 自動裝置設定。 請遵循此對應項目架構：
{
"properties": {
"desired": {
"azureiot*com^dtracing^1": {
"sampling_mode": 1,
"sampling_rate": 100
}
}
}
}
| 元素名稱 | 必要 | 類型 | 描述 |
|---|---|---|---|
sampling_mode |
Yes | 整數 | 目前支援兩個模式值來開啟和關閉取樣。 1 為開啟，且 2 為關閉。 |
sampling_rate |
Yes | 整數 | 此值是百分比。 只允許從 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 中的一些範例記錄：
| 產生的時間 | 作業名稱 | 類別 | 層級 | 相互關聯 ID | 以毫秒為單位的持續時間 | 屬性 |
|---|---|---|---|---|---|---|
| 2018-02-22T03：28：28.633Z | DiagnosticIoTHubD2C | DistributedTracing | 資訊 | 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 | 資訊 | 00-8cd869a412459a25f5b4f31311223344-349810a9bbd28730-01 | 20 | {"isRoutingEnabled":"false","parentSpanId":"0144d2590aacd909"} |
| 2018-02-22T03：28：48.633Z | DiagnosticIoTHubEgress | DistributedTracing | 資訊 | 00-8cd869a412459a25f5b4f31311223344-349810a9bbd28730-01 | 23 | {"endpointType":"EventHub","endpointName":"myEventHub", "parentSpanId":"0144d2590aacd909"} |
若要了解記錄的類型，請參閱 Azure IoT 中樞 分散式追蹤記錄。
執行範例應用程式
在本節中，您會準備開發環境以搭配 Azure IoT C SDK 使用。 然後，您可以修改其中一個範例，以在裝置的遙測訊息上啟用分散式追蹤。
這些指示適用於在 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 中樞 功能啟用原則。 使用額外的程式代碼行啟用POLICY_CONFIGURATION_DISTRIBUTED_TRACING之後，裝置的追蹤行為會反映裝置對應項上所做的分散式追蹤變更。若要讓範例應用程式保持執行，而不用完所有配額，請在傳送訊息循環結束時新增一秒的延遲：
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 目錄移至
iothub_ll_telemetry_sample專案目錄，azure-iot-sdk-c/cmake然後編譯範例：cd iothub_client/samples/iothub_ll_telemetry_sample cmake --build . --target iothub_ll_telemetry_sample --config Debug執行應用程式。 裝置會傳送支持分散式追蹤的遙測。
Debug/iothub_ll_telemetry_sample.exe讓應用程式保持執行。 您可以在主控台視窗中觀察傳送至 IoT 中樞 的訊息。
針對可從雲端接收取樣決策的用戶端應用程式，請嘗試 分散式追蹤範例存放庫中的 iothub_devicetwin_sample.c 範例。
非 Microsoft 用戶端的因應措施
實作分散式追蹤功能而不使用 C SDK 會比較複雜。 不建議這樣做。
首先，您必須遵循開發人員指南建立和讀取 IoT 中樞 訊息，在您的訊息中實作所有 IoT 中樞 通訊協定基本類型。 然後，編輯 MQTT 和 AMQP 訊息中的通訊協定屬性，以新增 tracestate 為系統屬性。
具體而言：
- 針對 MQTT，請將 新增
%24.tracestate=timestamp%3d1539243209至訊息主題。 以 Unix 時間戳格式的訊息建立時間取代1539243209。 例如，請參閱 C SDK 中的 實作。 - 針對AMQP，新增
key("tracestate")和value("timestamp=1539243209")作為訊息批注。 如需參考實作，請參閱 uamqp_messaging.c 檔案。
若要控制包含此屬性的訊息百分比，請實作邏輯來接聽雲端起始的事件，例如對應項更新。
下一步
- 若要深入瞭解微服務中的一般分散式追蹤模式，請參閱 微服務架構模式：分散式追蹤。