Überwachen von Gerät-zu-Cloud-Nachrichten in Azure IoT mit der verteilten Ablaufverfolgung (Vorschau)

Verwenden Sie die verteilte Ablaufverfolgung (Preview) in IoT Hub, um IoT-Nachrichten zu überwachen, während sie Azure-Dienste durchlaufen. IoT Hub ist einer der ersten Azure-Dienste, der die verteilte Ablaufverfolgung unterstützt. Da immer mehr Azure-Dienste die verteilte Ablaufverfolgung unterstützen, sind Sie in der Lage, Internet der Dinge (IoT)-Nachrichten über alle an Ihrer Lösung beteiligten Azure-Dienste hinweg zu verfolgen. Weitere Informationen zu dieser Funktion finden Sie unter Was ist die verteilte Ablaufverfolgung?.

Das Aktivieren der verteilten Ablaufverfolgung für IoT Hub ermöglicht Ihnen Folgendes:

• Überwachen Sie den Flow jeder Nachricht in IoT Hub mit dem Ablaufverfolgungskontext. Der Ablaufverfolgungskontext umfasst Korrelations-IDs, mit denen Sie Ereignisse von einer Komponente mit Ereignissen einer anderen Komponente korrelieren können. Sie können diese Funktion mithilfe eines Gerätezwillings auf einige oder alle IoT-Gerätenachrichten anwenden.
• Protokollieren Sie den Überwachungskontext in Azure Monitor-Protokollen.
• Messen und analysieren Sie den Nachrichtenfluss sowie die Latenzen von Geräten zu IoT Hub und Routingendpunkten.

Wichtig

Die verteilte Ablaufverfolgung eines Azure IoT Hub befindet sich derzeit in der PREVIEW. Die zusätzlichen Nutzungsbestimmungen für Microsoft Azure-Vorschauen enthalten rechtliche Bedingungen. Sie gelten für diejenigen Azure-Features, die sich in der Beta- oder Vorschauversion befinden oder aber anderweitig noch nicht zur allgemeinen Verfügbarkeit freigegeben sind.

Voraussetzungen

• Ein Azure IoT-Hub, der in einer der folgenden Regionen erstellt wurde.

  • Nordeuropa
  • Asien, Südosten
  • USA, Westen 2

• Ein bei Ihrem IoT-Hub registriertes Gerät. Wenn Sie keine haben, folgen Sie den Schritten unter Registrieren eines neuen Geräts im IoT-Hub und speichern Sie die Verbindungszeichenfolge des Geräts zur Verwendung in diesem Artikel.

• In diesem Artikel wird davon ausgegangen, dass Sie mit dem Senden von Telemetrienachrichten an Ihre IoT Hub-Instanz vertraut sind.

• Die neueste Version von Git.

Einschränkungen und Anmerkungen zur Public Preview

Beachten Sie die folgenden Einschränkungen, um festzustellen, ob diese Vorschaufunktion für Ihre Szenarien geeignet ist:

• Der Vorschlag für den W3C-Standard zum Ablaufverfolgungskontext ist aktuell ein Arbeitsentwurf.

• Die einzige Entwicklungssprache, die das Client-SDK derzeit unterstützt, ist C, im Public Preview Branch des Azure IoT Geräte-SDK für C

• Die Funktion für Cloud-zu-Gerät-Zwillinge ist für den Basic-Tarif von IoT Hub nicht verfügbar. Dennoch führt IoT Hub die Protokollierung in Azure Monitor durch, wenn ordnungsgemäß erstellte Kontextheader für die Ablaufverfolgung erkannt werden.

• Um einen effizienten Betrieb sicherzustellen, wird in IoT Hub eine Drosselung für die Protokollierungsrate festgelegt, die als Teil der verteilten Ablaufverfolgung erfolgen kann.

• Die Funktion zur verteilten Ablaufverfolgung wird nur für IoT-Hubs unterstützt, die in den folgenden Regionen erstellt wurden:

  • Nordeuropa
  • Asien, Südosten
  • USA, Westen 2

Grundlegendes zur verteilten Ablaufverfolgung in Azure IoT

Viele IoT-Lösungen, einschließlich der Azure IoT-Referenzarchitektur, folgen in der Regel einer Variante der Microservicearchitektur. Mit zunehmender Komplexität einer IoT-Lösung nutzen Sie schließlich ein Dutzend oder mehr Microservices. Diese Microservices können aus Azure oder anderen Quellen stammen.

Die genaue Ermittlung, an welcher Stelle IoT-Nachrichten gelöscht oder langsamer übertragen werden, kann schwierig sein. Angenommen, Ihre IoT-Lösung nutzt fünf unterschiedliche Azure-Dienste und umfasst 1.500 aktive Geräte. Jedes Gerät sendet zehn Gerät-zu-Cloud-Nachrichten pro Sekunde, was insgesamt 15.000 Nachrichten pro Sekunde entspricht. Sie bemerken jedoch, dass Ihre Web-App nur 10.000 Nachrichten pro Sekunde erhält. Wie finden Sie den Verursacher?

Damit der Weg einer IoT-Nachricht dienstübergreifend nachvollzogen werden kann, muss jeder Dienst eine Korrelations-ID weitergeben, mit der die Nachricht eindeutig identifiziert wird. Nachdem Azure Monitor Korrelations-IDs in einem zentralen System erfasst hat, können Sie diese IDs verwenden, um den Nachrichtenfluss anzuzeigen. Diese Methode wird als Muster der verteilten Ablaufverfolgung bezeichnet.

Zur Unterstützung einer größeren Akzeptanz der verteilten Ablaufverfolgung beteiligt sich Microsoft am Vorschlag für den W3C-Standard für die verteilte Ablaufverfolgung. Nach der Aktivierung erfolgt die Unterstützung der verteilten Ablaufverfolgung für IoT Hub für jede generierte Nachricht nach diesem Muster:

1. Auf dem IoT-Gerät wird eine Nachricht generiert.
2. Das IoT-Gerät legt fest (mit Unterstützung der Cloud), dass dieser Nachricht ein Ablaufverfolgungskontext zugewiesen werden soll.
3. Das SDK fügt der Nachrichteneigenschaft einen tracestate-Wert hinzu, der den Zeitstempel für die Nachrichtenerstellung enthält.
4. Das IoT-Gerät sendet die Nachricht an IoT Hub.
5. Die Nachricht wird am IoT Hub-Gateway empfangen.
6. IoT Hub sucht in den Nachrichteneigenschaften nach dem tracestate-Wert und überprüft, ob er im richtigen Format vorliegt. Wenn dies der Fall ist, generiert IoT Hub einen global eindeutigen trace-id-Wert für die Nachricht und einen span-id-Wert für den „Hop“. IoT Hub zeichnet diese Werte in den IoT Hub-Protokollen für die verteilte Ablaufverfolgung unter dem Vorgang DiagnosticIoTHubD2C auf.
7. Nach Abschluss der Nachrichtenverarbeitung generiert IoT Hub einen weiteren span-id-Wert und protokolliert ihn zusammen mit dem vorhandenen trace-id-Wert unter dem Vorgang DiagnosticIoTHubIngress.
8. Wenn für die Nachricht das Routing aktiviert ist, schreibt IoT Hub die Nachricht in den benutzerdefinierten Endpunkt. IoT Hub protokolliert einen weiteren span-id-Wert mit dem gleichen trace-id-Wert unter der Kategorie DiagnosticIoTHubEgress.

Konfigurieren der verteilten Ablaufverfolgung in einem IoT-Hub

In diesem Abschnitt konfigurieren Sie einen IoT-Hub zum Protokollieren der Attribute der verteilten Ablaufverfolgung (Korrelations-IDs und Zeitstempel).

1. Navigieren Sie im Azure-Portal zu Ihrem IoT-Hub.

2. Scrollen Sie im linken Bereich für den IoT-Hub nach unten zum Abschnitt Überwachung, und wählen Sie Diagnoseeinstellungen aus.

3. Klicken Sie auf Diagnoseeinstellung hinzufügen.

4. Geben Sie im Feld Name der Diagnoseeinstellung einen Namen für die neue Diagnoseeinstellung ein. Geben Sie z. B. DistributedTracingSettings ein.

   

5. Wählen Sie eine oder mehrere der folgenden Optionen unter Zieldetails aus, um festzulegen, wohin die Protokollierung gesendet wird:

   • In einem Speicherkonto archivieren: Konfigurieren Sie ein Speicherkonto für die Protokollierungsinformationen.
   • An einen Event Hub streamen: Konfigurieren Sie einen Event Hub für die Protokollierungsinformationen.
   • An Log Analytics senden: Konfigurieren Sie einen Log Analytics-Arbeitsbereich für die Protokollierungsinformationen.

6. Wählen Sie im Abschnitt Protokolle die Vorgänge aus, die Sie protokollieren möchten.

   Aktivieren Sie Verteilte Ablaufverfolgung, und konfigurieren Sie unter Aufbewahrung (Tage) einen Aufbewahrungszeitraum für die Protokollierung. Der Aufbewahrungszeitraum von Protokollen wirkt sich auf die Speicherkosten aus.

   

7. Wählen Sie Speichern.

8. (Optional:) Damit die Nachrichten in verschiedene Speicherorte übertragen werden, richten Sie Routingregeln an mindestens zwei unterschiedlichen Endpunkten ein.

Nachdem die Protokollierung aktiviert wurde, wird bei Nachrichten mit gültigen Ablaufverfolgungseigenschaften in folgenden Fällen ein Protokoll in IoT Hub aufgezeichnet:

• Die Nachricht wird am Gateway des IoT-Hubs empfangen.
• Der IoT-Hub verarbeitet die Nachricht.
• Die Nachricht wird an benutzerdefinierte Endpunkte weitergeleitet. Das Routing muss aktiviert sein.

Weitere Informationen zu diesen Protokollen und deren Schemas finden Sie unter Überwachen von IoT Hub und Verteilte Ablaufverfolgung in IoT Hub-Ressourcenprotokollen.

Aktualisieren von Samplingoptionen

Um den Prozentsatz der in der Cloud zu überwachenden Nachrichten zu ändern, müssen Sie den Gerätezwilling aktualisieren. Sie können Aktualisierungen mithilfe des JSON-Editors im Azure-Portal oder mit dem IoT Hub Service SDK vornehmen. Beispiele dafür finden Sie in den folgenden Abschnitten.

Aktualisieren eines einzelnen Geräts

Sie können das Azure-Portal oder die Azure IoT Hub-Erweiterung für Visual Studio Code (VS Code) verwenden, um die Samplingrate eines einzelnen Geräts zu aktualisieren.

Azure portal

1. Gehen Sie zu Ihrem IoT-Hub im Azure-Portal und wählen Sie dann die Option Geräte im Menü unter Geräteverwaltung.

2. Wählen Sie Ihr Gerät aus.

3. Wählen Sie das Zahnradsymbol unter Verteilte Ablaufverfolgung (Preview) aus. Führen Sie im daraufhin angezeigten Bereich die folgenden Schritte aus:

   1. Wählen Sie die Option Aktivieren aus.
   2. Wählen Sie für Samplingrate einen Prozentsatz zwischen 0 und 100 aus.
   3. Wählen Sie Speichern aus.

   

4. Warten Sie einige Sekunden, und wählen Sie dann Aktualisieren aus. Wenn das Gerät die Änderungen erfolgreich bestätigt, wird ein Synchronisierungssymbol mit einem Häkchen angezeigt.

VS-Code

1. Vergewissern Sie sich, dass Visual Studio Code installiert ist, und installieren Sie die aktuelle Version der Azure IoT Hub-Erweiterung für Visual Studio Code.

2. Öffnen Sie Visual Studio Code, wechseln Sie zur Registerkarte Explorer und dann zum Abschnitt Azure IoT Hub.

3. Wählen Sie die Auslassungspunkte (...) neben Azure IoT Hub aus, um ein Untermenü anzuzeigen. Wählen Sie die Option IoT Hub auswählen aus, um Ihren IoT-Hub aus Azure abzurufen.

   Im Popupfenster, das oben in Visual Studio Code angezeigt wird, können Sie Ihr Abonnement und den IoT-Hub-auswählen.

   Eine Demo finden Sie auf der GitHub-Seite vscode-azure-iot-toolkit.

4. Erweitern Sie unter Geräte Ihr Gerät. Klicken Sie mit der rechten Maustaste auf Einstellung für verteilte Ablaufverfolgung (Vorschau), und wählen Sie dann Einstellung für verteilte Ablaufverfolgung aktualisieren (Vorschau) aus.

5. Wählen Sie im Popupbereich, der oben im Fenster angezeigt wird, die Option Aktivieren aus.

   

   Unter Einstellung für verteilte Ablaufverfolgung (Vorschau)>Gewünscht wird jetzt Verteilte Ablaufverfolgung aktivieren: Aktiviert angezeigt.

6. Geben Sie im Popupbereich, der für die Samplingrate angezeigt wird, einen Integer zwischen 0 und 100 ein und drücken Sie dann die Eingabetaste.

   

   Samplingrate: 100 % erscheint nun unter Einstellung für verteilte Ablaufverfolgung (Preview)>Gewünscht.

Massenaktualisierung für mehrere Geräte

Verwenden Sie zum Aktualisieren der Samplingkonfiguration der verteilten Ablaufverfolgung für mehrere Geräte die automatische Gerätekonfiguration. Befolgen Sie dazu das folgende Zwillingsschema:

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

Elementname	Erforderlich	Type	BESCHREIBUNG
sampling_mode	Ja	Integer	Derzeit werden zum Aktivieren und Deaktivieren des Samplings zwei Moduswerte unterstützt. 1 steht für „Aktiviert“ und 2 für „Deaktiviert“.
sampling_rate	Ja	Integer	Dieser Wert ist ein Prozentsatz. Es sind nur Werte von 0 bis (einschließlich) 100 zulässig.

Abfragen und Visualisieren der Ablaufverfolgung

Um alle von einer IoT Hub-Instanz protokollierten Ablaufverfolgungen anzuzeigen, fragen Sie den Protokollspeicher ab, den Sie in den Diagnoseeinstellungen ausgewählt haben. In diesem Abschnitt wird gezeigt, wie Sie Abfragen mithilfe von Log Analytics durchführen.

Wenn Sie Log Analytics mit Ressourcenprotokollen einrichten, führen Sie die Abfragen durch Suchen nach Protokollen in der Kategorie DistributedTracing durch. Die folgende Abfrage zeigt beispielsweise alle protokollierten Ablaufverfolgungen an:

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

Hier sehen Sie einige Beispielprotokolle in Log Analytics:

Generierungszeit	Vorgangsname	Category	Ebene	Korrelations-ID	Dauer in Millisekunden	Eigenschaften
2018-02-22T03:28:28.633Z	DiagnosticIoTHubD2C	DistributedTracing	Informational	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	Informational	00-8cd869a412459a25f5b4f31311223344-349810a9bbd28730-01	20	{"isRoutingEnabled":"false","parentSpanId":"0144d2590aacd909"}
2018-02-22T03:28:48.633Z	DiagnosticIoTHubEgress	DistributedTracing	Informational	00-8cd869a412459a25f5b4f31311223344-349810a9bbd28730-01	23	{"endpointType":"EventHub","endpointName":"myEventHub", "parentSpanId":"0144d2590aacd909"}

Eine Beschreibung der Protokolltypen finden Sie unter Azure IoT Hub-Protokolle für verteilte Ablaufverfolgung.

Ausführen einer Beispielanwendung

In diesem Abschnitt bereiten Sie eine Entwicklungsumgebung zur Verwendung mit dem Azure IoT C SDK vor. Anschließend ändern Sie eines der Beispiele, um die verteilte Ablaufverfolgung für die Telemetriedaten des Geräts zu aktivieren.

Diese Anweisungen betreffen die Erstellung des Beispiels unter Windows. Informationen zu anderen Umgebungen finden Sie unter Compile the C SDK (Kompilieren des C SDK) oder Prepackaged C SDK for Platform Specific Development (Vorkonfiguriertes C SDK für plattformspezifische Entwicklung).

Klonen des Quellcodes und Initialisieren

1. Installieren Sie die Workload Desktopentwicklung mit C++ für Visual Studio 2022. Visual Studio 2019 wird ebenfalls unterstützt.

2. Installieren Sie CMake. Stellen Sie sicher, dass CMake in Ihrem PATH enthalten ist, indem Sie an einer Eingabeaufforderung cmake -version eingeben.

3. Öffnen Sie eine Eingabeaufforderung oder die Git Bash-Shell. Führen Sie die folgenden Befehle zum Klonen des aktuellen Releases des Public Preview-Branches des GitHub-Repositorys Azure IoT C SDK aus:

   git clone -b public-preview https://github.com/Azure/azure-iot-sdk-c.git
   cd azure-iot-sdk-c
   git submodule update --init
   

   Dieser Vorgang kann mehrere Minuten dauern.

4. Führen Sie die folgenden Befehle im Verzeichnis azure-iot-sdk-c aus, um ein Unterverzeichnis cmake zu erstellen und zum Ordner cmake zu wechseln:

   mkdir cmake
   cd cmake
   cmake ..
   

   Wenn CMake Ihren C++-Compiler nicht findet, können beim Ausführen des obigen Befehls Buildfehler auftreten. Führen Sie den Befehl in diesem Fall an der Visual Studio-Eingabeaufforderung aus.

   Nach erfolgreicher Erstellung ähneln die letzten Ausgabezeilen der folgenden Ausgabe:

   $ 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
   

Bearbeiten des Telemetriebeispiels zum Aktivieren der verteilten Ablaufverfolgung

In diesem Abschnitt bearbeiten Sie das Beispiel iothub_ll_telemetry_sample.c im SDK-Repository, um die verteilte Ablaufverfolgung zu aktivieren. Alternativ können Sie eine bereits bearbeitete Version des Beispiels aus dem Repository azure-iot-distributed-tracing-sample kopieren.

1. Öffnen Sie die Quelldatei azure-iot-sdk-c/iothub_client/samples/iothub_ll_telemetry_sample/iothub_ll_telemetry_sample.c in einem Editor.

2. Suchen Sie die Deklaration der 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;
   

   Ersetzen Sie den Wert der Konstante connectionString durch die Geräteverbindungszeichenfolge, die Sie im Abschnitt Registrieren eines Geräts des Schnellstarts zum Senden von Telemetriedaten notiert haben.

3. Suchen Sie die Codezeile, über die IoTHubDeviceClient_LL_SetConnectionStatusCallback aufgerufen wird, um eine Rückruffunktion des Verbindungsstatus vor der Schleife zum Senden von Nachrichten zu registrieren. Fügen Sie unter dieser Zeile Code hinzu, um IoTHubDeviceClient_LL_EnablePolicyConfiguration aufzurufen und die verteilte Ablaufverfolgung für das Gerät zu aktivieren:

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

   Die Funktion IoTHubDeviceClient_LL_EnablePolicyConfiguration aktiviert Richtlinien für spezifische IoT Hub-Funktionen, die über Gerätezwillinge konfiguriert werden. Nachdem Sie POLICY_CONFIGURATION_DISTRIBUTED_TRACING mithilfe der zusätzlichen Codezeile aktiviert haben, entspricht das Ablaufverfolgungsverhalten des Geräts den Änderungen für die verteilte Ablaufverfolgung, die am Gerätezwilling vorgenommen wurden.

4. Damit die Beispiel-App ausgeführt wird, ohne dass Ihr gesamtes Kontingent aufgebraucht wird, fügen Sie am Ende der Schleife zum Senden von Nachrichten eine Verzögerung von einer Sekunde hinzu:

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

Kompilieren und Ausführen

1. Navigieren Sie im zuvor erstellten CMake-Verzeichnis (azure-iot-sdk-c/cmake) zum Projektverzeichnis iothub_ll_telemetry_sample, und kompilieren Sie das Beispiel:

   cd iothub_client/samples/iothub_ll_telemetry_sample
   cmake --build . --target iothub_ll_telemetry_sample --config Debug
   

2. Führen Sie die Anwendung aus. Das Gerät sendet Telemetriedaten, die die verteilte Ablaufverfolgung unterstützen.

   Debug/iothub_ll_telemetry_sample.exe
   

3. Führen Sie die App weiter aus. Sie können die Nachrichten, die an IoT Hub gesendet werden, im Konsolenfenster beobachten.

Für eine Client-Anwendung, die Sampling-Entscheidungen aus der Cloud empfangen kann, probieren Sie das Beispiel iothub_devicetwin_sample.c aus dem Repository „distributed tracing sample“ aus.

Problemumgehung für Nicht-Microsoft-Clients

Die Implementierung der verteilten Ablaufverfolgung ohne Verwendung des C SDK ist komplexer. Wir raten davon ab.

Zunächst müssen Sie alle einfachen IoT Hub-Protokolltypen in Ihren Nachrichten implementieren, indem Sie dem Entwicklerleitfaden Erstellen und Lesen von IoT Hub-Nachrichten folgen. Anschließend bearbeiten Sie die Protokolleigenschaften in den MQTT- und AMQP-Nachrichten, um tracestate als Systemeigenschaft hinzuzufügen.

Dies betrifft insbesondere:

• Fügen Sie für MQTT %24.tracestate=timestamp%3d1539243209 zum Nachrichtenthema hinzu. Ersetzen Sie 1539243209 durch die Erstellungszeit der Nachricht im UNIX-Zeitstempelformat. Ein Beispiel hierfür ist die Implementierung im C SDK.
• Für AMQP fügen Sie key("tracestate") und value("timestamp=1539243209") als Nachrichtenanmerkung hinzu. Eine Referenzimplementierung finden Sie in der Datei uamqp_messaging.c.

Wenn Sie den Prozentsatz der Nachrichten, die diese Eigenschaft enthalten, steuern möchten, implementieren Sie Logik zum Lauschen auf in der Cloud initiierte Ereignisse, z. B. Zwillingsaktualisierungen.

Nächste Schritte

• Weitere Informationen zum allgemeinen Muster der verteilten Ablaufverfolgung in Microservices finden Sie unter Microservice architecture pattern: distributed tracing (Microservicearchitekturmuster: Verteilte Ablaufverfolgung).