Trasování zpráv zařízení-cloud v Azure IoT pomocí distribuovaného trasování (Preview)

Článek
03/05/2024

Pomocí distribuovaného trasování (Preview) ve službě IoT Hub můžete monitorovat zprávy IoT při jejich průchodu službami Azure. IoT Hub je jednou z prvních služeb Azure, které podporují distribuované trasování. Vzhledem k tomu, že více služeb Azure podporuje distribuované trasování, můžete sledovat zprávy Internetu věcí (IoT) ve všech službách Azure, které jsou součástí vašeho řešení. Další informace o této funkci najdete v tématu Co je distribuované trasování?.

Když povolíte distribuované trasování pro IoT Hub, můžete:

Monitorujte tok každé zprávy přes IoT Hub pomocí kontextu trasování. Kontext trasování obsahuje ID korelace, která umožňují korelaci událostí z jedné komponenty s událostmi z jiné komponenty. Můžete ji použít pro podmnožinu nebo všechny zprávy zařízení IoT pomocí dvojčete zařízení.
Protokolujte kontext trasování do protokolů služby Azure Monitor.
Změřte a pochopte tok zpráv a latenci ze zařízení do ioT Hubu a koncových bodů směrování.

Důležité

Distribuované trasování služby Azure IoT Hub je aktuálně ve verzi PREVIEW. Právní podmínky, které platí pro funkce Azure, které jsou ve verzi beta, verzi Preview nebo které zatím nejsou veřejně dostupné, najdete v Dodatečných podmínkách použití pro Microsoft Azure verze Preview.

Požadavky

Centrum Azure IoT vytvořené v jedné z následujících oblastí.
- Severní Evropa
- Southeast Asia
- Západní USA 2
Zařízení zaregistrované ve službě IoT Hub. Pokud ve službě IoT Hub nemáte zařízení, postupujte podle pokynů v části Registrace zařízení a uložte připojovací řetězec zařízení, abyste ho mohli použít v tomto článku.
Tento článek předpokládá, že znáte odesílání telemetrických zpráv do centra IoT.
Nejnovější verze Gitu

Omezení a aspekty verze Public Preview

Zvažte následující omezení, abyste zjistili, jestli je tato funkce ve verzi Preview pro vaše scénáře správná:

Návrh standardu W3C Trace Context je v současné době funkčním konceptem.
Jediným vývojovým jazykem, který klientská sada SDK aktuálně podporuje, je jazyk C ve větvi public Preview sady SDK pro zařízení Azure IoT pro jazyk C.
Funkce dvojčete typu cloud-zařízení není dostupná pro úroveň Basic služby IoT Hub. IoT Hub se ale stále protokoluje do služby Azure Monitor, pokud se zobrazí správně složená hlavička kontextu trasování.
Kvůli zajištění efektivní operace ioT Hub omezuje rychlost protokolování, ke které může dojít v rámci distribuovaného trasování.
Distribuovaná funkce trasování je podporovaná jenom pro ioT Huby vytvořené v následujících oblastech:
- Severní Evropa
- Southeast Asia
- Západní USA 2

Vysvětlení distribuovaného trasování Azure IoT

Řada řešení IoT, včetně referenční architektury Azure IoT, se obecně řídí variantou architektury mikroslužeb. Vzhledem k tomu, že řešení IoT roste komplexněji, budete nakonec používat desítky nebo více mikroslužeb. Tyto mikroslužby můžou nebo nemusí být z Azure.

Určení místa, kde se zprávy IoT zahazují nebo zpomalují, můžou být náročné. Představte si například, že máte řešení IoT, které používá pět různých služeb Azure a 1 500 aktivních zařízení. Každé zařízení odesílá 10 zpráv typu zařízení-cloud za sekundu za celkem 15 000 zpráv za sekundu. Všimli jste si ale, že vaše webová aplikace vidí jenom 10 000 zpráv za sekundu. Jak zjistíte viníka?

Aby bylo potřeba rekonstruovat tok zprávy IoT napříč službami, měla by každá služba rozšířit ID korelace, které zprávu jednoznačně identifikuje. Jakmile Azure Monitor shromažďuje ID korelace v centralizovaném systému, můžete pomocí těchto ID zobrazit tok zpráv. Tato metoda se nazývá model distribuovaného trasování.

Microsoft přispívá ke standardnímu návrhu W3C pro distribuované trasování, aby podporoval širší přijetí distribuovaného trasování. Pokud je povolená podpora distribuovaného trasování pro IoT Hub, postupuje podle tohoto toku pro každou vygenerovanou zprávu:

V zařízení IoT se vygeneruje zpráva.
Zařízení IoT se rozhodne (s pomocí z cloudu), že by tato zpráva měla být přiřazena s kontextem trasování.
Sada SDK přidá tracestate hodnotu do vlastnosti zprávy, která obsahuje časové razítko pro vytvoření zprávy.
Zařízení IoT odešle zprávu do IoT Hubu.
Zpráva se dorazí do brány IoT Hubu.
IoT Hub vyhledá tracestate hodnotu ve vlastnostech zprávy a zkontroluje, jestli je ve správném formátu. Pokud ano, IoT Hub vygeneruje globálně jedinečnou trace-id hodnotu zprávy a span-id hodnotu pro segment směrování. IoT Hub tyto hodnoty zaznamenává v protokolech distribuovaného trasování ve službě DiagnosticIoTHubD2C IoT Hub v rámci operace.
Po dokončení zpracování zpráv ioT Hub vygeneruje další span-id hodnotu a zaprokoluje ji spolu s existující trace-id hodnotou v rámci DiagnosticIoTHubIngress operace.
Pokud je pro zprávu povolené směrování, Služba IoT Hub ji zapíše do vlastního koncového bodu. IoT Hub zaznamená jinou span-id hodnotu se stejnou trace-id hodnotou v DiagnosticIoTHubEgress kategorii.

Konfigurace distribuovaného trasování ve službě IoT Hub

V této části nakonfigurujete Centrum IoT tak, aby protokoloval atributy distribuovaného trasování (ID korelace a časová razítka).

Na webu Azure Portal přejděte do centra IoT.
V levém podokně centra IoT přejděte dolů do části Monitorování a vyberte Nastavení diagnostiky.
Vyberte Přidat nastavení diagnostiky.
Do pole Název nastavení diagnostiky zadejte název nového nastavení diagnostiky. Zadejte například DistributedTracingSettings.
V části Podrobnosti o cíli zvolte jednu nebo více z následujících možností a určete, kam se mají odesílat informace o protokolování:
- Archivace do účtu úložiště: Nakonfigurujte účet úložiště tak, aby obsahoval informace o protokolování.
- Streamování do centra událostí: Nakonfigurujte centrum událostí tak, aby obsahovalo informace o protokolování.
- Odeslání do Log Analytics: Nakonfigurujte pracovní prostor služby Log Analytics tak, aby obsahoval informace o protokolování.
V části Protokoly vyberte operace, které chcete protokolovat.

Zahrňte distribuované trasování a nakonfigurujte dobu uchovávání informací po dobu, po kterou chcete protokolování zachovat. Uchovávání protokolů má vliv na náklady na úložiště.
Zvolte Uložit.
(Volitelné) Pokud chcete zobrazit tok zpráv na různá místa, nastavte pravidla směrování na alespoň dva různé koncové body.

Jakmile je protokolování zapnuté, IoT Hub zaznamená protokol, když se v některé z následujících situací zobrazí zpráva obsahující platné vlastnosti trasování:

Zpráva se dorazí do brány centra IoT.
IoT Hub zpracuje zprávu.
Zpráva se směruje na vlastní koncové body. Musí být povolené směrování.

Další informace o těchto protokolech a jejich schématech najdete v tématu Monitorování ioT Hubu a distribuovaného trasování v protokolech prostředků služby IoT Hub.

Aktualizace možností vzorkování

Pokud chcete změnit procento zpráv, které se mají sledovat z cloudu, musíte aktualizovat dvojče zařízení. Aktualizace můžete provádět pomocí editoru JSON na webu Azure Portal nebo sady SDK služby IoT Hub. Následující pododdíly obsahují příklady.

Aktualizace jednoho zařízení

Pomocí webu Azure Portal nebo rozšíření Azure IoT Hub pro Visual Studio Code (VS Code) můžete aktualizovat vzorkovací frekvenci jednoho zařízení.

Azure Portal
VS Code

Na webu Azure Portal přejděte do centra IoT a v části Správa zařízení v nabídce vyberte Zařízení.
Zvolte své zařízení.
V části Distribuované trasování (Preview) vyberte ikonu ozubeného kola. Na panelu, který se otevře:
1. Vyberte možnost Povolit.
2. Pro vzorkovací frekvenci zvolte procento mezi 0 a 100.
3. Zvolte Uložit.
Počkejte několik sekund a pak vyberte Aktualizovat. Pokud zařízení vaše změny úspěšně potvrdí, zobrazí se ikona synchronizace se značkou zaškrtnutí.

Hromadná aktualizace více zařízení

Pokud chcete aktualizovat konfiguraci vzorkování distribuovaného trasování pro více zařízení, použijte automatickou konfiguraci zařízení. Postupujte podle tohoto schématu dvojčete:

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

Název prvku	Požaduje se	Type	Popis
`sampling_mode`	Ano	Celé číslo	Pro zapnutí a vypnutí vzorkování se v současné době podporují dvě hodnoty režimu. `1` je zapnutá a `2` je vypnutá.
`sampling_rate`	Ano	Celé číslo	Tato hodnota je procento. Jsou povoleny pouze hodnoty od `0` do `100` (včetně).

Dotazování a vizualizace trasování

Pokud chcete zobrazit všechna trasování protokolovaná centrem IoT, zadejte dotaz na úložiště protokolů, které jste vybrali v nastavení diagnostiky. Tato část ukazuje, jak dotazovat pomocí Log Analytics.

Pokud nastavíte Log Analytics s protokoly prostředků, dotazujte se vyhledáním protokolů v DistributedTracing kategorii. Tento dotaz například zobrazuje všechny protokolované trasování:

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

Tady je několik ukázkových protokolů v Log Analytics:

Čas vygenerování	Název operace	Kategorie	Level	ID korelace	Doba trvání v milisekundách	Vlastnosti
2018-02-22T03:28:28.633Z	DiagnosticIoTHubD2C	DistributedTracing	Informační	00-8cd869a412459a25f5b4f311223344-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	Informační	00-8cd869a412459a25f5b4f311223344-349810a9bbd28730-01	20	`{"isRoutingEnabled":"false","parentSpanId":"0144d2590aacd909"}`
2018-02-22T03:28:48.633Z	DiagnosticIoTHubEgress	DistributedTracing	Informační	00-8cd869a412459a25f5b4f311223344-349810a9bbd28730-01	23	`{"endpointType":"EventHub","endpointName":"myEventHub", "parentSpanId":"0144d2590aacd909"}`

Informace o typech protokolů najdete v distribuovaných protokolech trasování ve službě Azure IoT Hub.

Spuštění ukázkové aplikace

V této části připravíte vývojové prostředí pro použití se sadou Azure IoT C SDK. Potom upravíte jednu z ukázek tak, aby umožňovala distribuované trasování ve zprávách telemetrie vašeho zařízení.

Tyto pokyny slouží k vytvoření ukázky ve Windows. Další prostředí najdete v tématu Kompilace sady C SDK nebo předem zabalené sady C SDK pro vývoj pro konkrétní platformu.

Klonování zdrojového kódu a inicializace

Nainstalujte vývoj desktopových aplikací pomocí úlohy C++ pro Visual Studio 2022. Podporuje se také Visual Studio 2019.
Nainstalujte CMake. Zadáním z příkazového řádku se ujistěte, že je ve vašem PATH cmake -version počítači.
Otevřete prostředí příkazového řádku nebo Git Bash. Spuštěním následujících příkazů naklonujte nejnovější verzi větve public-preview úložiště GitHub sady Azure IoT C SDK :
```
git clone -b public-preview https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c
git submodule update --init
```
Očekáváme, že dokončení této operace bude trvat několik minut.
Spuštěním následujících příkazů z azure-iot-sdk-c adresáře vytvořte cmake podadresář a přejděte do cmake složky:
```
mkdir cmake
cd cmake
cmake ..
```
Pokud CMake nemůže najít kompilátor C++, může při spuštění předchozího příkazu dojít k chybám sestavení. Pokud k tomu dojde, zkuste příkaz spustit v příkazovém řádku sady Visual Studio.

Po úspěšném sestavení bude několik posledních výstupních řádků vypadat podobně jako v následujícím výstupu:
```
$ 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
```

Úprava ukázky telemetrie pro povolení distribuovaného trasování

V této části upravíte ukázku iothub_ll_telemetry_sample.c v úložišti sady SDK a povolíte distribuované trasování. Nebo můžete zkopírovat již upravenou verzi ukázky z úložiště azure-iot-distributed-tracing-sample .

Otevřete zdrojový soubor pomocí editoru azure-iot-sdk-c/iothub_client/samples/iothub_ll_telemetry_sample/iothub_ll_telemetry_sample.c .

Vyhledejte deklaraci konstanty 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 Hodnotu konstanty nahraďte připojovací řetězec zařízení, které jste uložili v části Registrace zařízení v rychlém startu pro odesílání telemetrie.

Najděte řádek kódu, který volá IoTHubDeviceClient_LL_SetConnectionStatusCallback , aby před smyčkou odeslání zprávy zaregistroval funkci zpětného volání stavu připojení. Přidejte kód pod tento řádek pro volání IoTHubDeviceClient_LL_EnablePolicyConfiguration a povolte distribuované trasování pro zařízení:
```
// 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)
```
Tato IoTHubDeviceClient_LL_EnablePolicyConfiguration funkce umožňuje zásady pro konkrétní funkce IoT Hubu, které jsou nakonfigurované prostřednictvím dvojčat zařízení. Po povolení POLICY_CONFIGURATION_DISTRIBUTED_TRACING pomocí dalšího řádku kódu bude chování trasování zařízení odrážet distribuované změny trasování provedené ve dvojčeti zařízení.

Pokud chcete, aby ukázková aplikace běžela bez použití celé kvóty, přidejte na konec smyčky odeslání zprávy jednosekundové zpoždění:

    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);

Kompilace a spuštění

Přejděte do iothub_ll_telemetry_sample adresáře projektu z adresáře CMake (azure-iot-sdk-c/cmake), který jste vytvořili dříve, a zkompilujte ukázku:
```
cd iothub_client/samples/iothub_ll_telemetry_sample
cmake --build . --target iothub_ll_telemetry_sample --config Debug
```
Aplikaci spusťte. Zařízení odesílá telemetrii, která podporuje distribuované trasování.
```
Debug/iothub_ll_telemetry_sample.exe
```
Nechte aplikaci spuštěnou. V okně konzoly můžete sledovat, jak se zprávy odesílají do IoT Hubu.

V případě klientské aplikace, která může přijímat rozhodnutí o vzorkování z cloudu, zkuste ukázku iothub_devicetwin_sample.c v distribuovaném úložišti ukázek trasování.

Alternativní řešení pro klienty jiných společností než Microsoft

Implementace funkce distribuovaného trasování bez použití sady C SDK je složitější. Nedoporučujeme ho.

Nejprve musíte implementovat všechny primitivy protokolu IoT Hubu ve zprávách podle příručky pro vývojáře: Vytvoření a čtení zpráv IoT Hubu. Potom upravte vlastnosti protokolu ve zprávách MQTT a AMQP tak, aby se přidaly tracestate jako systémová vlastnost.

Konkrétně:

Pro MQTT přidejte %24.tracestate=timestamp%3d1539243209 do tématu zprávy. Nahraďte 1539243209 časem vytvoření zprávy ve formátu časového razítka systému Unix. Jako příklad se podívejte na implementaci v sadě C SDK.
Pro AMQP přidejte key("tracestate") a value("timestamp=1539243209") jako poznámku zprávy. Referenční implementaci naleznete v souboru uamqp_messaging.c .

Chcete-li řídit procento zpráv obsahujících tuto vlastnost, implementujte logiku pro naslouchání událostem iniciovaných v cloudu, jako jsou aktualizace dvojčete.

Další kroky

Další informace o obecném vzoru distribuovaného trasování v mikroslužbách najdete v tématu Model architektury mikroslužeb: distribuované trasování.

Sdílet prostřednictvím