使用分散式追蹤來追蹤 Azure IoT 裝置到雲端的訊息 (預覽)

發行項
06/26/2024

在 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 中樞基本層。不過，如果 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 值。IoT 中樞會在 DiagnosticIoTHubD2C 作業之下的 IoT 中樞分散式追蹤記錄中記錄這些值。
訊息處理完成時，IoT 中樞會產生另一個 span-id 值，並將其與現有 trace-id 值一起記錄在作業 DiagnosticIoTHubIngress 底下。
如果啟用訊息的路由功能，IoT 中樞將訊息寫入到自訂端點。 IoT 中樞會將另一個 span-id 值與相同的 trace-id 值記錄在 DiagnosticIoTHubEgress 類別底下。

在 IoT 中樞設定分散式追蹤

在本節中，您會設定 IoT 中樞以記錄分散式追蹤屬性 (相互關聯識別碼和時間戳記)。

在 Azure 入口網站中，移至您的 IoT 中樞。
在 IoT 中樞的左窗格中，向下捲動至 [監視] 區段，然後選取 [診斷設定]。
選取 [新增診斷設定]。
在 [診斷設定名稱] 方塊中，輸入新診斷設定的名稱。例如，DistributedTracingSettings。
在 [目的地詳細資料] 底下選擇下列一或多個選項，以決定要將記錄資訊傳送到哪裡：
- 封存至儲存體帳戶：設定儲存體帳戶以包含記錄資訊。
- 串流至事件中樞：設定事件中樞以包含記錄資訊。
- 傳送至 Log Analytics：設定記錄分析工作區來包含記錄資訊。
在 [記錄] 區段中，選取您想要記錄的作業。

包含 DistributedTracing，並針對您想要保留記錄的天數設定 [保留] 期間。記錄保留會影響儲存成本。
選取 [儲存]。
(選擇性) 若要查看流向不同地方的訊息，請設定送到至少兩個不同端點的路由規則。

開啟記錄功能後，在下列任何情況下遇到包含有效追蹤屬性的訊息時，IoT 中樞就會記載記錄：

訊息抵達 IoT 中樞閘道。
IoT 中樞會處理訊息。
訊息已路由傳送到自訂端點。必須啟用路由。

若要深入了解這些記錄及其結構描述，請參閱監視 IoT 中樞和 IoT 中樞資源記錄中的分散式追蹤。

更新取樣選項

若要變更要從雲端追蹤的訊息百分比，您必須更新裝置對應項。您可以在 Azure 入口網站或 IoT 中樞服務 SDK 中使用 JSON 編輯器來進行更新。下列各小節提供相關範例。

更新單一裝置

您可以使用 Azure 入口網站或適用於 Visual Studio Code (VS Code) 的 Azure IoT 中樞延伸模組來更新單一裝置的取樣率。

Azure 入口網站
VS Code

移至 Azure 入口網站中的 IoT 中樞，然後從功能表的 [裝置管理] 區段中選取 [裝置]。
選擇您的裝置。
在 [分散式追蹤 (預覽)] 底下，選取齒輪圖示。在開啟的面板中：
1. 選取 [啟用] 選項。
2. 針對 [取樣率]，選擇介於 0 到 100 之間的百分比。
3. 選取 [儲存]。
請稍等片刻，然後選取 [重新整理]。如果裝置成功認可您的變更，即會出現具有核取記號的同步圖示。

大量更新多個裝置

若要更新多個裝置的分散式追蹤取樣組態，請使用自動裝置組態。遵循此對應項架構：

{
    "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 檔案。

若要控制包含此屬性的訊息百分比，請實作邏輯以接聽雲端起始的事件，例如對應項更新。

下一步

若要深入了解微服務中的一般分散式追蹤模式，請參閱微服務架構模式：分散式追蹤。

共用方式為