Azure IoT-apparaat-naar-cloud-berichten traceren met behulp van gedistribueerde tracering (preview)

Artikel
03/05/2024

Gebruik gedistribueerde tracering (preview) in IoT Hub om IoT-berichten te bewaken wanneer ze azure-services passeren. IoT Hub is een van de eerste Azure-services ter ondersteuning van gedistribueerde tracering. Naarmate meer Azure-services gedistribueerde tracering ondersteunen, kunt u IoT-berichten (Internet of Things) traceren in de Azure-services die bij uw oplossing betrokken zijn. Zie Wat is gedistribueerde tracering? voor meer informatie over de functie.

Wanneer u gedistribueerde tracering inschakelt voor IoT Hub, kunt u het volgende doen:

Bewaak de stroom van elk bericht via IoT Hub met behulp van traceringscontext. Traceringscontext bevat correlatie-id's waarmee u gebeurtenissen van het ene onderdeel kunt correleren met gebeurtenissen van een ander onderdeel. U kunt deze toepassen op een subset of alle IoT-apparaatberichten met behulp van een apparaatdubbel.
De traceringscontext registreren bij Azure Monitor-logboeken.
Meet en begrijp de berichtenstroom en latentie van apparaten naar IoT Hub en routeringseindpunten.

Belangrijk

Gedistribueerde tracering van een Azure IoT Hub bevindt zich momenteel in PREVIEW. Raadpleeg de Aanvullende voorwaarden voor Microsoft Azure-previews voor juridische voorwaarden die van toepassing zijn op Azure-functies die in bèta of preview zijn of die anders nog niet algemeen beschikbaar zijn.

Vereisten

Een Azure IoT-hub die is gemaakt in een van de volgende regio's.
- Europa - noord
- Azië - zuidoost
- VS - west 2
Een apparaat dat is geregistreerd bij uw IoT-hub. Als u nog geen apparaat hebt, volgt u de stappen in Een nieuw apparaat registreren in de IoT-hub en slaat u het apparaat op verbindingsreeks voor gebruik in dit artikel.
In dit artikel wordt ervan uitgegaan dat u bekend bent met het verzenden van telemetrieberichten naar uw IoT-hub.
De nieuwste versie van Git.

Limieten en overwegingen voor openbare preview

Houd rekening met de volgende beperkingen om te bepalen of deze preview-functie geschikt is voor uw scenario's:

Het voorstel voor de W3C Trace Context-standaard is momenteel een werkend concept.
De enige ontwikkeltaal die momenteel door de client-SDK wordt ondersteund, is C, in de openbare preview-vertakking van de Azure IoT Device SDK voor C
Cloud-naar-apparaatdubbelfunctie is niet beschikbaar voor de Basic-laag van IoT Hub. IoT Hub meldt zich echter nog steeds aan bij Azure Monitor als er een correct samengestelde traceringscontextheader wordt weergegeven.
Om een efficiënte werking te garanderen, legt IoT Hub een beperking op voor de snelheid van logboekregistratie die kan optreden als onderdeel van gedistribueerde tracering.
De functie gedistribueerde tracering wordt alleen ondersteund voor IoT-hubs die zijn gemaakt in de volgende regio's:
- Europa - noord
- Azië - zuidoost
- VS - west 2

Informatie over gedistribueerde tracering van Azure IoT

Veel IoT-oplossingen, waaronder de Referentiearchitectuur van Azure IoT, volgen doorgaans een variant van de microservicearchitectuur. Naarmate een IoT-oplossing complexer wordt, gebruikt u uiteindelijk een dozijn of meer microservices. Deze microservices zijn mogelijk wel of niet afkomstig van Azure.

Het kan lastig zijn om te bepalen waar IoT-berichten worden neergeslagen of vertraagd. Stel dat u een IoT-oplossing hebt die gebruikmaakt van vijf verschillende Azure-services en 1500 actieve apparaten. Elk apparaat verzendt 10 apparaat-naar-cloud-berichten per seconde, voor een totaal van 15.000 berichten per seconde. U ziet echter dat uw web-app slechts 10.000 berichten per seconde ziet. Hoe vind je de schuldige?

Voor het reconstrueren van de stroom van een IoT-bericht tussen services, moet elke service een correlatie-id doorgeven die het bericht uniek identificeert. Nadat Azure Monitor correlatie-id's in een gecentraliseerd systeem verzamelt, kunt u deze id's gebruiken om de berichtenstroom te bekijken. Deze methode wordt het patroon gedistribueerde tracering genoemd.

Om een bredere acceptatie voor gedistribueerde tracering te ondersteunen, draagt Microsoft bij aan het W3C-standaardvoorstel voor gedistribueerde tracering. Wanneer ondersteuning voor gedistribueerde tracering voor IoT Hub is ingeschakeld, volgt deze stroom voor elk gegenereerd bericht:

Er wordt een bericht gegenereerd op het IoT-apparaat.
Het IoT-apparaat bepaalt (met hulp van de cloud) dat dit bericht moet worden toegewezen met een traceringscontext.
De SDK voegt een tracestate waarde toe aan de berichteigenschap, die het tijdstempel voor het maken van berichten bevat.
Het IoT-apparaat verzendt het bericht naar IoT Hub.
Het bericht komt aan bij de IoT Hub-gateway.
IoT Hub zoekt naar de tracestate waarde in de berichteigenschappen en controleert of deze de juiste indeling heeft. Zo ja, dan genereert IoT Hub een wereldwijd unieke trace-id waarde voor het bericht en een span-id waarde voor de 'hop'. IoT Hub registreert deze waarden in de gedistribueerde traceringslogboeken van IoT Hub onder de DiagnosticIoTHubD2C bewerking.
Wanneer de berichtverwerking is voltooid, genereert IoT Hub een andere span-id waarde en registreert deze, samen met de bestaande trace-id waarde, onder de DiagnosticIoTHubIngress bewerking.
Als routering is ingeschakeld voor het bericht, schrijft IoT Hub het naar het aangepaste eindpunt. IoT Hub registreert een andere span-id waarde met dezelfde trace-id waarde onder de DiagnosticIoTHubEgress categorie.

Gedistribueerde tracering configureren in een IoT-hub

In deze sectie configureert u een IoT-hub voor het vastleggen van gedistribueerde traceringskenmerken (correlatie-id's en tijdstempels).

Ga naar uw IoT-hub in Azure Portal.
Schuif in het linkerdeelvenster voor uw IoT-hub omlaag naar de sectie Bewaking en selecteer diagnostische instellingen.
Selecteer Diagnostische instellingen toevoegen.
Voer in het vak Naam van diagnostische instelling een naam in voor een nieuwe diagnostische instelling. Voer bijvoorbeeld DistributedTracing Instellingen in.
Kies een of meer van de volgende opties onder Doelgegevens om te bepalen waar logboekgegevens moeten worden verzonden:
- Archiveren naar een opslagaccount: configureer een opslagaccount dat de logboekgegevens bevat.
- Streamen naar een Event Hub: Een Event Hub configureren om de logboekgegevens te bevatten.
- Verzenden naar Log Analytics: configureer een Log Analytics-werkruimte die de logboekgegevens bevat.
Selecteer in de sectie Logboeken de bewerkingen die u wilt vastleggen.

Neem gedistribueerde tracering op en configureer een bewaarperiode voor het aantal dagen dat u de logboekregistratie wilt behouden. Logboekretentie is van invloed op de opslagkosten.
Selecteer Opslaan.
(Optioneel) Als u wilt zien dat berichten naar verschillende locaties stromen, stelt u routeringsregels in op ten minste twee verschillende eindpunten.

Nadat de logboekregistratie is ingeschakeld, registreert IoT Hub een logboek wanneer een bericht met geldige traceringseigenschappen wordt aangetroffen in een van de volgende situaties:

Het bericht komt aan bij de gateway van de IoT-hub.
De IoT-hub verwerkt het bericht.
Het bericht wordt doorgestuurd naar aangepaste eindpunten. Routering moet zijn ingeschakeld.

Zie IoT Hub en gedistribueerde tracering bewaken in resourcelogboeken van IoT Hub voor meer informatie over deze logboeken en hun schema's.

Opties voor het bijwerken van steekproeven

Als u het percentage berichten wilt wijzigen dat moet worden getraceerd vanuit de cloud, moet u de apparaatdubbel bijwerken. U kunt updates uitvoeren met behulp van de JSON-editor in Azure Portal of de IoT Hub-service-SDK. De volgende subsecties bevatten voorbeelden.

Eén apparaat bijwerken

U kunt Azure Portal of de Azure IoT Hub-extensie voor Visual Studio Code (VS Code) gebruiken om de steekproeffrequentie van één apparaat bij te werken.

Azure-portal
VS-code

Ga naar uw IoT-hub in Azure Portal en selecteer vervolgens Apparaten in de sectie Apparaatbeheer van het menu.
Kies uw apparaat.
Selecteer het tandwielpictogram onder Gedistribueerde tracering (preview). In het deelvenster dat wordt geopend:
1. Selecteer de optie Inschakelen .
2. Kies voor samplingfrequentie een percentage tussen 0 en 100.
3. Selecteer Opslaan.
Wacht een paar seconden en selecteer Vernieuwen. Als het apparaat uw wijzigingen heeft bevestigd, wordt er een synchronisatiepictogram met een vinkje weergegeven.

Meerdere apparaten bulksgewijs bijwerken

Als u de configuratie voor steekproeven voor gedistribueerde tracering voor meerdere apparaten wilt bijwerken, gebruikt u de automatische apparaatconfiguratie. Volg dit dubbelschema:

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

Naam van element	Vereist	Type	Description
`sampling_mode`	Ja	Geheel getal	Er worden momenteel twee moduswaarden ondersteund voor het in- en uitschakelen van steekproeven. `1` is ingeschakeld en `2` is uitgeschakeld.
`sampling_rate`	Ja	Geheel getal	Deze waarde is een percentage. Alleen waarden van `0` tot `100` (inclusief) zijn toegestaan.

Traceringen opvragen en visualiseren

Als u alle traceringen wilt zien die zijn geregistreerd door een IoT-hub, voert u een query uit in het logboekarchief dat u hebt geselecteerd in diagnostische instellingen. In deze sectie ziet u hoe u query's kunt uitvoeren met behulp van Log Analytics.

Als u Log Analytics instelt met resourcelogboeken, voert u een query uit door te zoeken naar logboeken in de DistributedTracing categorie. In deze query worden bijvoorbeeld alle vastgelegde traceringen weergegeven:

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

Hier volgen enkele voorbeeldlogboeken in Log Analytics:

Tijd gegenereerd	Bewerkingsnaam	Categorie	Niveau	Correlatie-id	Duur in milliseconden	Eigenschappen
2018-02-22T03:28:28.633Z	DiagnosticIoTHubD2C	Gedistribueerdetracering	Informatief	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	Gedistribueerdetracering	Informatief	00-8cd869a412459a25f5b4f31311223344-349810a9bbd28730-01	20	`{"isRoutingEnabled":"false","parentSpanId":"0144d2590aacd909"}`
2018-02-22T03:28:48.633Z	DiagnosticIoTHubEgress	Gedistribueerdetracering	Informatief	00-8cd869a412459a25f5b4f31311223344-349810a9bbd28730-01	23	`{"endpointType":"EventHub","endpointName":"myEventHub", "parentSpanId":"0144d2590aacd909"}`

Zie gedistribueerde traceringslogboeken van Azure IoT Hub voor meer informatie over de typen logboeken.

Een voorbeeldtoepassing uitvoeren

In deze sectie bereidt u een ontwikkelomgeving voor voor gebruik met de Azure IoT C SDK. Vervolgens wijzigt u een van de voorbeelden om gedistribueerde tracering in te schakelen op de telemetrieberichten van uw apparaat.

Deze instructies zijn bedoeld voor het bouwen van het voorbeeld in Windows. Zie Compileer de C SDK of de vooraf verpakte C SDK voor platformspecifieke ontwikkeling voor andere omgevingen.

De broncode klonen en initialiseren

Installeer de desktopontwikkeling met C++ -workload voor Visual Studio 2022. Visual Studio 2019 wordt ook ondersteund.
Installeer CMake. Zorg ervoor dat deze zich in uw PATH computer voorkomt door vanaf een opdrachtprompt in te voeren cmake -version .
Open een opdrachtprompt of Git Bash-shell. Voer de volgende opdrachten uit om de nieuwste versie van de openbare preview-vertakking van de GitHub-opslagplaats van de Azure IoT C SDK te klonen:
```
git clone -b public-preview https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c
git submodule update --init
```
Verwacht dat het enkele minuten duren voordat deze bewerking is voltooid.
Voer de volgende opdrachten uit vanuit de azure-iot-sdk-c map om een cmake submap te maken en ga naar de cmake map:
```
mkdir cmake
cd cmake
cmake ..
```
Als CMake uw C++-compiler niet kan vinden, kunnen er buildfouten optreden tijdens het uitvoeren van de voorgaande opdracht. Als dit gebeurt, voert u de opdracht uit in de Visual Studio-opdrachtprompt.

Nadat de build is voltooid, zien de laatste uitvoerregels er ongeveer als volgt uit:
```
$ 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
```

Het telemetrievoorbeeld bewerken om gedistribueerde tracering in te schakelen

In deze sectie bewerkt u het iothub_ll_telemetry_sample.c-voorbeeld in de SDK-opslagplaats om gedistribueerde tracering in te schakelen. U kunt ook een reeds bewerkte versie van het voorbeeld kopiëren uit de opslagplaats azure-iot-distributed-tracing-sample .

Gebruik een editor om het azure-iot-sdk-c/iothub_client/samples/iothub_ll_telemetry_sample/iothub_ll_telemetry_sample.c bronbestand te openen.
Zoek de declaratie van de connectionString constante:
```
/* 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;
```
Vervang de waarde van de connectionString constante door het apparaat verbindingsreeks dat u hebt opgeslagen in de sectie Een apparaat registreren van de quickstart voor het verzenden van telemetrie.
Zoek de coderegel die aanroept IoTHubDeviceClient_LL_SetConnectionStatusCallback om een callbackfunctie voor de verbindingsstatus te registreren voordat de berichtenlus wordt verzonden. Voeg onder die regel code toe om gedistribueerde tracering voor het apparaat aan te roepen IoTHubDeviceClient_LL_EnablePolicyConfiguration en in te schakelen:
```
// 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)
```
De IoTHubDeviceClient_LL_EnablePolicyConfiguration functie maakt beleidsregels mogelijk voor specifieke IoT Hub-functies die zijn geconfigureerd via apparaatdubbels. Nadat u de extra coderegel hebt gebruikt POLICY_CONFIGURATION_DISTRIBUTED_TRACING , geeft het traceringsgedrag van het apparaat gedistribueerde traceringswijzigingen weer die zijn aangebracht op de apparaatdubbel.

Als u de voorbeeld-app actief wilt houden zonder al uw quotum te gebruiken, voegt u een vertraging van één seconde toe aan het einde van de verzendberichtlus:

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

Compileren en uitvoeren

Ga naar de iothub_ll_telemetry_sample projectmap vanuit de CMake-map (azure-iot-sdk-c/cmake) die u eerder hebt gemaakt en compileer het voorbeeld:
```
cd iothub_client/samples/iothub_ll_telemetry_sample
cmake --build . --target iothub_ll_telemetry_sample --config Debug
```
Voer de toepassing uit. Het apparaat verzendt telemetrie die gedistribueerde tracering ondersteunt.
```
Debug/iothub_ll_telemetry_sample.exe
```
Houd de app actief. U kunt in het consolevenster zien welke berichten naar IoT Hub worden verzonden.

Voor een client-app die steekproeven kan nemen van de cloud, probeert u het voorbeeld iothub_devicetwin_sample.c in de voorbeeldopslagplaats voor gedistribueerde tracering.

Tijdelijke oplossing voor niet-Microsoft-clients

Het implementeren van de functie gedistribueerde tracering zonder de C SDK is complexer. We raden het niet aan.

Eerst moet u alle Primitieven van het IoT Hub-protocol in uw berichten implementeren door de ontwikkelaarshandleiding IoT Hub-berichten te maken en te lezen. Bewerk vervolgens de protocoleigenschappen in de MQTT- en AMQP-berichten die moeten worden toegevoegd tracestate als een systeemeigenschap.

Specifiek:

Voor MQTT voegt u dit toe %24.tracestate=timestamp%3d1539243209 aan het berichtonderwerp. Vervang 1539243209 door de aanmaaktijd van het bericht in unix-tijdstempelindeling. Raadpleeg bijvoorbeeld de implementatie in de C SDK.
Voor AMQP voegt u aantekening toe key("tracestate") en value("timestamp=1539243209") als berichtaantekening. Zie het bestand uamqp_messaging.c voor een referentie-implementatie.

Als u het percentage berichten met deze eigenschap wilt beheren, implementeert u logica om te luisteren naar door de cloud geïnitieerde gebeurtenissen, zoals dubbelupdates.

Volgende stappen

Zie het patroon microservicearchitectuur: gedistribueerde tracering voor meer informatie over het algemene patroon voor gedistribueerde tracering in microservices.