Spåra Azure IoT-meddelanden från enhet till moln med hjälp av distribuerad spårning (förhandsversion)

Artikel
03/05/2024

Använd distribuerad spårning (förhandsversion) i IoT Hub för att övervaka IoT-meddelanden när de passerar genom Azure-tjänster. IoT Hub är en av de första Azure-tjänsterna som stöder distribuerad spårning. Eftersom fler Azure-tjänster stöder distribuerad spårning kan du spåra IoT-meddelanden (Internet of Things) i de Azure-tjänster som ingår i din lösning. Mer information om funktionen finns i Vad är distribuerad spårning?.

När du aktiverar distribuerad spårning för IoT Hub kan du:

Övervaka flödet för varje meddelande via IoT Hub med hjälp av spårningskontext. Spårningskontexten innehåller korrelations-ID:er som gör att du kan korrelera händelser från en komponent med händelser från en annan komponent. Du kan använda den för en delmängd eller alla IoT-enhetsmeddelanden med hjälp av en enhetstvilling.
Logga spårningskontexten till Azure Monitor-loggar.
Mät och förstå meddelandeflöde och svarstid från enheter till IoT Hub och routningsslutpunkter.

Viktigt!

Distribuerad spårning av en Azure IoT Hub finns för närvarande i FÖRHANDSVERSION. Juridiska villkor för Azure-funktioner i betaversion, förhandsversion eller som av någon annan anledning inte har gjorts allmänt tillgängliga ännu finns i kompletterande användningsvillkor för Microsoft Azure-förhandsversioner.

Förutsättningar

En Azure IoT-hubb som skapats i någon av följande regioner.
- Europa, norra
- Sydostasien
- Västra USA 2
En enhet som är registrerad i din IoT-hubb. Om du inte har en enhet i din IoT-hubb följer du stegen i Registrera en enhet och sparar enheten anslutningssträng som ska användas i den här artikeln.
Den här artikeln förutsätter att du är bekant med att skicka telemetrimeddelanden till din IoT-hubb.
Den senaste versionen av Git.

Begränsningar och överväganden för offentlig förhandsversion

Överväg följande begränsningar för att avgöra om den här förhandsgranskningsfunktionen är rätt för dina scenarier:

Förslaget till W3C Trace Context-standarden är för närvarande ett fungerande utkast.
Det enda utvecklingsspråk som klient-SDK:n stöder för närvarande är C, i den offentliga förhandsversionsgrenen för Azure IoT-enhets-SDK för C
Kapacitet för moln-till-enhet-tvilling är inte tillgänglig för IoT Hub-basnivån. IoT Hub loggar dock fortfarande till Azure Monitor om det ser ett korrekt sammansatt spårningskontexthuvud.
För att säkerställa effektiv drift inför IoT Hub en begränsning av loggningshastigheten som kan ske som en del av distribuerad spårning.
Funktionen distribuerad spårning stöds endast för IoT-hubbar som skapats i följande regioner:
- Europa, norra
- Sydostasien
- Västra USA 2

Förstå distribuerad Azure IoT-spårning

Många IoT-lösningar, inklusive Azure IoT-referensarkitekturen, följer vanligtvis en variant av mikrotjänstarkitekturen. När en IoT-lösning blir mer komplex får du ett dussin eller fler mikrotjänster. Dessa mikrotjänster kanske eller kanske inte kommer från Azure.

Det kan vara svårt att hitta var IoT-meddelanden släpper eller saktar ner. Anta till exempel att du har en IoT-lösning som använder fem olika Azure-tjänster och 1 500 aktiva enheter. Varje enhet skickar 10 meddelanden från enhet till moln per sekund, totalt 15 000 meddelanden per sekund. Men du märker att webbappen bara ser 10 000 meddelanden per sekund. Hur hittar du den skyldige?

För att du ska kunna rekonstruera flödet av ett IoT-meddelande mellan tjänster bör varje tjänst sprida ett korrelations-ID som unikt identifierar meddelandet. När Azure Monitor har samlat in korrelations-ID:t i ett centraliserat system kan du använda dessa ID:er för att se meddelandeflödet. Den här metoden kallas för det distribuerade spårningsmönstret.

För att stödja ett bredare införande för distribuerad spårning bidrar Microsoft till W3C-standardförslaget för distribuerad spårning. När stöd för distribuerad spårning för IoT Hub är aktiverat följer det det här flödet för varje genererat meddelande:

Ett meddelande genereras på IoT-enheten.
IoT-enheten bestämmer (med hjälp av molnet) att det här meddelandet ska tilldelas med en spårningskontext.
SDK:t lägger till ett tracestate värde i meddelandeegenskapen, som innehåller tidsstämpeln för att skapa meddelanden.
IoT-enheten skickar meddelandet till IoT Hub.
Meddelandet kommer till IoT Hub-gatewayen.
IoT Hub söker tracestate efter värdet i meddelandeegenskaperna och kontrollerar om det är i rätt format. I så fall genererar IoT Hub ett globalt unikt trace-id värde för meddelandet och ett span-id värde för "hopp". IoT Hub registrerar dessa värden i IoT Hub-distribuerade spårningsloggar under åtgärden DiagnosticIoTHubD2C .
När meddelandebearbetningen är klar genererar IoT Hub ett annat span-id värde och loggar det, tillsammans med det befintliga trace-id värdet, under åtgärden DiagnosticIoTHubIngress .
Om routning är aktiverat för meddelandet skriver IoT Hub det till den anpassade slutpunkten. IoT Hub loggar ett annat span-id värde med samma trace-id värde under DiagnosticIoTHubEgress kategorin.

Konfigurera distribuerad spårning i en IoT-hubb

I det här avsnittet konfigurerar du en IoT-hubb för att logga distribuerade spårningsattribut (korrelations-ID och tidsstämplar).

Gå till din IoT-hubb i Azure Portal.
I den vänstra rutan för din IoT-hubb rullar du ned till avsnittet Övervakning och väljer Diagnostikinställningar.
Välj Lägg till diagnostikinställning.
I rutan Namn på diagnostikinställning anger du ett namn för en ny diagnostikinställning. Ange till exempel DistributedTracingSettings.
Välj ett eller flera av följande alternativ under Målinformation för att avgöra var loggningsinformation ska skickas:
- Arkivera till ett lagringskonto: Konfigurera ett lagringskonto så att det innehåller loggningsinformationen.
- Strömma till en händelsehubb: Konfigurera en händelsehubb så att den innehåller loggningsinformationen.
- Skicka till Log Analytics: Konfigurera en Log Analytics-arbetsyta så att den innehåller loggningsinformationen.
I avsnittet Loggar väljer du de åtgärder som du vill logga.

Inkludera distribuerad spårning och konfigurera en kvarhållningsperiod för hur många dagar du vill att loggningen ska behållas. Loggkvarhållning påverkar lagringskostnaderna.
Välj Spara.
(Valfritt) Om du vill se meddelandena flöda till olika platser konfigurerar du routningsregler till minst två olika slutpunkter.

När loggningen är aktiverad registrerar IoT Hub en logg när ett meddelande som innehåller giltiga spårningsegenskaper påträffas i någon av följande situationer:

Meddelandet kommer till IoT-hubbens gateway.
IoT-hubben bearbetar meddelandet.
Meddelandet dirigeras till anpassade slutpunkter. Routning måste vara aktiverat.

Mer information om dessa loggar och deras scheman finns i Övervaka IoT Hub och distribuerad spårning i IoT Hub-resursloggar.

Alternativ för uppdateringssampling

Om du vill ändra procentandelen meddelanden som ska spåras från molnet måste du uppdatera enhetstvillingen. Du kan göra uppdateringar med JSON-redigeraren i Azure Portal eller IoT Hub-tjänstens SDK. Följande underavsnitt innehåller exempel.

Uppdatera en enskild enhet

Du kan använda Azure Portal eller Azure IoT Hub-tillägget för Visual Studio Code (VS Code) för att uppdatera samplingsfrekvensen för en enskild enhet.

Azure-portalen
VS-kod

Gå till din IoT-hubb i Azure Portal och välj sedan Enheter i avsnittet Enhetshantering på menyn.
Välj din enhet.
Välj kugghjulsikonen under Distribuerad spårning (förhandsversion). I panelen som öppnas:
1. Välj alternativet Aktivera.
2. För Samplingshastighet väljer du en procentandel mellan 0 och 100.
3. Välj Spara.
Vänta några sekunder och välj sedan Uppdatera. Om enheten bekräftar dina ändringar visas en synkroniseringsikon med en bockmarkering.

Massuppdatering av flera enheter

Om du vill uppdatera samplingskonfigurationen för distribuerad spårning för flera enheter använder du automatisk enhetskonfiguration. Följ det här tvillingschemat:

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

Elementnamn	Obligatoriskt	Type	Beskrivning
`sampling_mode`	Ja	Integer	Två lägesvärden stöds för närvarande för att aktivera och inaktivera sampling. `1` är på och `2` är avstängd.
`sampling_rate`	Ja	Integer	Det här värdet är en procentandel. Endast värden från `0` till `100` (inklusive) tillåts.

Fråga efter och visualisera spårningar

Om du vill se alla spårningar som loggas av en IoT-hubb frågar du loggarkivet som du valde i diagnostikinställningarna. Det här avsnittet visar hur du frågar med hjälp av Log Analytics.

Om du konfigurerar Log Analytics med resursloggar frågar du efter loggar i DistributedTracing kategorin. Den här frågan visar till exempel alla loggade spårningar:

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

Här är några exempelloggar i Log Analytics:

Skapat	Operationsnamn	Kategori	Nivå	Korrelations-ID	Varaktighet i millisekunder	Egenskaper
2018-02-22T03:28:28.633Z	DiagnosticIoTHubD2C	Distribuerad spårning	Information	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	Distribuerad spårning	Information	00-8cd869a412459a25f5b4f31311223344-349810a9bbd28730-01	20	`{"isRoutingEnabled":"false","parentSpanId":"0144d2590aacd909"}`
2018-02-22T03:28:48.633Z	DiagnosticIoTHubEgress	Distribuerad spårning	Information	00-8cd869a412459a25f5b4f31311223344-349810a9bbd28730-01	23	`{"endpointType":"EventHub","endpointName":"myEventHub", "parentSpanId":"0144d2590aacd909"}`

Information om vilka typer av loggar som finns i Distribuerade spårningsloggar i Azure IoT Hub.

Köra ett exempelprogram

I det här avsnittet förbereder du en utvecklingsmiljö för användning med Azure IoT C SDK. Sedan ändrar du ett av exemplen för att aktivera distribuerad spårning på enhetens telemetrimeddelanden.

De här anvisningarna är till för att skapa exemplet på Windows. Andra miljöer finns i Kompilera C SDK eller förpaketerad C SDK för plattformsspecifik utveckling.

Klona källkoden och initiera

Installera skrivbordsutvecklingen med C++- arbetsbelastningen för Visual Studio 2022. Visual Studio 2019 stöds också.
Installera CMake. Kontrollera att den finns i din PATH genom att ange cmake -version från en kommandotolk.
Öppna en kommandotolk eller Git Bash-gränssnittet. Kör följande kommandon för att klona den senaste versionen av den offentliga förhandsversionen av Azure IoT C SDK GitHub-lagringsplatsen:
```
git clone -b public-preview https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c
git submodule update --init
```
Förvänta dig att åtgärden tar flera minuter att slutföra.

Kör följande kommandon från azure-iot-sdk-c katalogen för att skapa en cmake underkatalog och gå till cmake mappen:

mkdir cmake
cd cmake
cmake ..

Om CMake inte hittar C++-kompilatorn kan det uppstå byggfel när du kör föregående kommando. Om det händer kan du prova att köra kommandot i Visual Studio-kommandotolken.

När bygget har slutförts ser de sista utdataraderna ut ungefär som följande utdata:

$ 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

Redigera telemetriexemplet för att aktivera distribuerad spårning

I det här avsnittet redigerar du exemplet iothub_ll_telemetry_sample.c på SDK-lagringsplatsen för att aktivera distribuerad spårning. Du kan också kopiera en redan redigerad version av exemplet från lagringsplatsen azure-iot-distributed-tracing-sample .

Använd en redigerare för att öppna azure-iot-sdk-c/iothub_client/samples/iothub_ll_telemetry_sample/iothub_ll_telemetry_sample.c källfilen.

Hitta deklarationen för konstanten 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;

Ersätt värdet för konstanten connectionString med enheten anslutningssträng som du sparade i avsnittet Registrera en enhet i snabbstarten för att skicka telemetri.

Leta reda på den kodrad som anropar IoTHubDeviceClient_LL_SetConnectionStatusCallback för att registrera en återanropsfunktion för anslutningsstatus innan meddelandeloopen skickas. Lägg till kod under raden för att anropa IoTHubDeviceClient_LL_EnablePolicyConfiguration och aktivera distribuerad spårning för enheten:
```
// 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)
```
Funktionen IoTHubDeviceClient_LL_EnablePolicyConfiguration aktiverar principer för specifika IoT Hub-funktioner som konfigureras via enhetstvillingar. När du har aktiverat POLICY_CONFIGURATION_DISTRIBUTED_TRACING med hjälp av den extra kodraden återspeglar spårningsbeteendet för enheten distribuerade spårningsändringar som gjorts på enhetstvillingen.

Om du vill hålla exempelappen igång utan att använda hela kvoten lägger du till en fördröjning på en sekund i slutet av meddelandeslingan:

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

Kompilera och kör

Gå till projektkatalogen iothub_ll_telemetry_sample från den CMake-katalog (azure-iot-sdk-c/cmake) som du skapade tidigare och kompilera exemplet:
```
cd iothub_client/samples/iothub_ll_telemetry_sample
cmake --build . --target iothub_ll_telemetry_sample --config Debug
```
Kör programmet. Enheten skickar telemetri som stöder distribuerad spårning.
```
Debug/iothub_ll_telemetry_sample.exe
```
Håll appen igång. Du kan se de meddelanden som skickas till IoT Hub i konsolfönstret.

För en klientapp som kan ta emot samplingsbeslut från molnet kan du prova iothub_devicetwin_sample.c-exemplet i den distribuerade lagringsplatsen för spårningsexempel.

Lösning för icke-Microsoft-klienter

Det är mer komplext att implementera funktionen distribuerad spårning utan att använda C SDK. Vi rekommenderar det inte.

Först måste du implementera alla IoT Hub-protokollprimitiver i dina meddelanden genom att följa utvecklarguiden Skapa och läsa IoT Hub-meddelanden. Redigera sedan protokollegenskaperna i MQTT- och AMQP-meddelandena för att lägga tracestate till som en systemegenskap.

Specifikt:

För MQTT lägger du till %24.tracestate=timestamp%3d1539243209 i meddelandeavsnittet. Ersätt 1539243209 med skapandetiden för meddelandet i Unix-tidsstämpelformat. Som ett exempel kan du referera till implementeringen i C SDK.
För AMQP lägger du till key("tracestate") och value("timestamp=1539243209") som meddelandeanteckning. En referensimplementering finns i filen uamqp_messaging.c .

Om du vill kontrollera procentandelen meddelanden som innehåller den här egenskapen implementerar du logik för att lyssna på molninitierade händelser, till exempel tvillinguppdateringar.

Nästa steg

Mer information om det allmänna mönstret för distribuerad spårning i mikrotjänster finns i Arkitekturmönster för mikrotjänster : distribuerad spårning.

Dela via