Śledzenie komunikatów z urządzenia do chmury usługi Azure IoT przy użyciu śledzenia rozproszonego (wersja zapoznawcza)

Śledzenie rozproszone (wersja zapoznawcza) w usłudze IoT Hub umożliwia monitorowanie komunikatów IoT podczas ich przekazywania przez usługi platformy Azure. Usługa IoT Hub jest jedną z pierwszych usług platformy Azure do obsługi śledzenia rozproszonego. Ponieważ więcej usług platformy Azure obsługuje śledzenie rozproszone, możesz śledzić komunikaty Internetu rzeczy (IoT) w usługach platformy Azure zaangażowanych w rozwiązanie. Aby uzyskać więcej informacji na temat funkcji, zobacz Co to jest śledzenie rozproszone?.

Po włączeniu śledzenia rozproszonego dla usługi IoT Hub można wykonywać następujące czynności:

• Monitoruj przepływ każdego komunikatu za pośrednictwem usługi IoT Hub przy użyciu kontekstu śledzenia. Kontekst śledzenia zawiera identyfikatory korelacji, które umożliwiają korelowanie zdarzeń z jednego składnika ze zdarzeniami z innego składnika. Można go zastosować dla podzestawu lub wszystkich komunikatów urządzenia IoT przy użyciu bliźniaczej reprezentacji urządzenia.
• Zarejestruj kontekst śledzenia w dziennikach usługi Azure Monitor.
• Mierzenie i zrozumienie przepływu komunikatów oraz opóźnienia z urządzeń do usługi IoT Hub i punktów końcowych routingu.

Ważne

Śledzenie rozproszone usługi Azure IoT Hub jest obecnie dostępne w wersji zapoznawczej. Zobacz Dodatkowe warunki użytkowania wersji zapoznawczych platformy Microsoft Azure, aby zapoznać się z postanowieniami prawnymi dotyczącymi funkcji platformy Azure, które są w wersji beta lub wersji zapoznawczej albo w inny sposób nie zostały jeszcze wydane jako ogólnie dostępne.

Wymagania wstępne

• Centrum Azure IoT Hub utworzone w jednym z następujących regionów.

  • Europa Północna
  • Southeast Asia
  • Zachodnie stany USA 2

• Urządzenie zarejestrowane w centrum IoT Hub. Jeśli nie masz urządzenia w centrum IoT Hub, wykonaj kroki opisane w artykule Rejestrowanie urządzenia i zapisz urządzenie parametry połączenia do użycia w tym artykule.

• W tym artykule założono, że wiesz już, jak wysyłać komunikaty telemetryczne do centrum IoT.

• Najnowsza wersja usługi Git.

Limity i zagadnienia dotyczące publicznej wersji zapoznawczej

Rozważ następujące ograniczenia, aby określić, czy ta funkcja w wersji zapoznawczej jest odpowiednia dla Twoich scenariuszy:

• Propozycja standardu kontekstowego śledzenia W3C jest obecnie roboczą wersją roboczą.

• Jedynym językiem programistycznym, który obecnie obsługuje zestaw SDK klienta, jest C, w publicznej gałęzi zapoznawczej zestawu SDK urządzenia Azure IoT dla języka C

• Funkcja bliźniaczej reprezentacji chmury do urządzenia nie jest dostępna dla warstwy podstawowej usługi IoT Hub. Jednak usługa IoT Hub nadal rejestruje się w usłudze Azure Monitor, jeśli widzi prawidłowo skomponowany nagłówek kontekstu śledzenia.

• Aby zapewnić wydajną operację, usługa IoT Hub nakłada ograniczenie szybkości rejestrowania, które może wystąpić w ramach śledzenia rozproszonego.

• Funkcja śledzenia rozproszonego jest obsługiwana tylko w przypadku centrów IoT utworzonych w następujących regionach:

  • Europa Północna
  • Southeast Asia
  • Zachodnie stany USA 2

Omówienie śledzenia rozproszonego usługi Azure IoT

Wiele rozwiązań IoT, w tym architektura referencyjna usługi Azure IoT, zwykle jest zgodne z wariantem architektury mikrousług. W miarę jak rozwiązanie IoT staje się coraz bardziej złożone, korzystasz z kilkunastu lub większej liczby mikrousług. Te mikrousługi mogą być lub nie pochodzić z platformy Azure.

Wskazanie, gdzie komunikaty IoT spadają lub spowalniają, mogą być trudne. Załóżmy na przykład, że masz rozwiązanie IoT korzystające z pięciu różnych usług platformy Azure i 1500 aktywnych urządzeń. Każde urządzenie wysyła 10 komunikatów z urządzenia do chmury na sekundę, łącznie 15 000 komunikatów na sekundę. Zauważysz jednak, że aplikacja internetowa widzi tylko 10 000 komunikatów na sekundę. Jak znaleźć winowajcę?

Aby odtworzyć przepływ komunikatu IoT między usługami, każda usługa powinna propagować identyfikator korelacji, który jednoznacznie identyfikuje komunikat. Gdy usługa Azure Monitor zbiera identyfikatory korelacji w scentralizowanym systemie, możesz użyć tych identyfikatorów, aby wyświetlić przepływ komunikatów. Ta metoda jest nazywana wzorcem śledzenia rozproszonego.

Aby zapewnić szerszą obsługę śledzenia rozproszonego, firma Microsoft współtworze standardową propozycję W3C dotyczącą śledzenia rozproszonego. Po włączeniu obsługi śledzenia rozproszonego dla usługi IoT Hub jest zgodny z tym przepływem dla każdego wygenerowanego komunikatu:

1. Na urządzeniu IoT jest generowany komunikat.
2. Urządzenie IoT decyduje (z pomocą chmury), że ten komunikat powinien zostać przypisany z kontekstem śledzenia.
3. Zestaw SDK dodaje tracestate wartość do właściwości komunikatu, która zawiera sygnaturę czasową tworzenia komunikatów.
4. Urządzenie IoT wysyła komunikat do usługi IoT Hub.
5. Komunikat zostanie wyświetlony w bramie usługi IoT Hub.
6. Usługa IoT Hub wyszukuje tracestate wartość we właściwościach komunikatu i sprawdza, czy jest w poprawnym formacie. Jeśli tak, usługa IoT Hub generuje globalnie unikatową trace-id wartość komunikatu i span-id wartość "przeskoku". Usługa IoT Hub rejestruje te wartości w dziennikach rozproszonego śledzenia usługi IoT Hub w DiagnosticIoTHubD2C ramach operacji.
7. Po zakończeniu przetwarzania komunikatów usługa IoT Hub generuje inną span-id wartość i rejestruje ją wraz z istniejącą trace-id wartością w ramach DiagnosticIoTHubIngress operacji.
8. Jeśli routing jest włączony dla komunikatu, usługa IoT Hub zapisuje go w niestandardowym punkcie końcowym. Usługa IoT Hub rejestruje inną span-id wartość o tej samej trace-id wartości w DiagnosticIoTHubEgress kategorii.

Konfigurowanie śledzenia rozproszonego w centrum IoT

W tej sekcji skonfigurujesz centrum IoT w celu rejestrowania atrybutów śledzenia rozproszonego (identyfikatory korelacji i sygnatury czasowe).

1. Przejdź do centrum IoT w witrynie Azure Portal.

2. W okienku po lewej stronie centrum IoT Hub przewiń w dół do sekcji Monitorowanie i wybierz pozycję Ustawienia diagnostyki.

3. Wybierz pozycję Dodaj ustawienia diagnostyczne.

4. W polu Nazwa ustawienia diagnostycznego wprowadź nazwę nowego ustawienia diagnostycznego. Na przykład wprowadź ciąg DistributedTracingSettings.

   

5. Wybierz co najmniej jedną z następujących opcji w obszarze Szczegóły miejsca docelowego, aby określić, gdzie mają być wysyłane informacje rejestrowania:

   • Archiwizowanie na koncie magazynu: skonfiguruj konto magazynu tak, aby zawierało informacje rejestrowania.
   • Przesyłanie strumieniowe do centrum zdarzeń: skonfiguruj centrum zdarzeń tak, aby zawierało informacje rejestrowania.
   • Wyślij do usługi Log Analytics: skonfiguruj obszar roboczy usługi Log Analytics, aby zawierał informacje rejestrowania.

6. W sekcji Dzienniki wybierz operacje, które chcesz rejestrować.

   Uwzględnij śledzenie rozproszone i skonfiguruj okres przechowywania dla liczby dni przechowywania. Przechowywanie dzienników wpływa na koszty magazynowania.

   

7. Wybierz pozycję Zapisz.

8. (Opcjonalnie) Aby wyświetlić przepływ komunikatów do różnych miejsc, skonfiguruj reguły routingu do co najmniej dwóch różnych punktów końcowych.

Po włączeniu rejestrowania usługa IoT Hub rejestruje dziennik, gdy w dowolnej z następujących sytuacji napotkano komunikat zawierający prawidłowe właściwości śledzenia:

• Komunikat pojawia się w bramie centrum IoT Hub.
• Centrum IoT przetwarza komunikat.
• Komunikat jest kierowany do niestandardowych punktów końcowych. Routing musi być włączony.

Aby dowiedzieć się więcej o tych dziennikach i ich schematach, zobacz Monitorowanie usługi IoT Hub i śledzenia rozproszonego w dziennikach zasobów usługi IoT Hub.

Aktualizowanie opcji próbkowania

Aby zmienić procent komunikatów, które mają być śledzone z chmury, należy zaktualizować bliźniacze reprezentację urządzenia. Aktualizacje można wprowadzać za pomocą edytora JSON w witrynie Azure Portal lub zestawu SDK usługi IoT Hub. Poniższe podsekcje zawierają przykłady.

Aktualizowanie pojedynczego urządzenia

Aby zaktualizować częstotliwość próbkowania jednego urządzenia, możesz użyć witryny Azure Portal lub rozszerzenia usługi Azure IoT Hub dla programu Visual Studio Code (VS Code).

Witryna Azure Portal

1. Przejdź do centrum IoT w witrynie Azure Portal, a następnie wybierz pozycję Urządzenia w sekcji Zarządzanie urządzeniami w menu.

2. Wybierz urządzenie.

3. Wybierz ikonę koła zębatego w obszarze Śledzenie rozproszone (wersja zapoznawcza). W wyświetlonym panelu:

   1. Wybierz opcję Włącz.
   2. W obszarze Częstotliwość próbkowania wybierz wartość procentową z zakresu od 0 do 100.
   3. Wybierz pozycję Zapisz.

   

4. Poczekaj kilka sekund, a następnie wybierz pozycję Odśwież. Jeśli urządzenie pomyślnie potwierdzi zmiany, zostanie wyświetlona ikona synchronizacji z znacznikiem wyboru.

VS Code

1. Po zainstalowaniu programu Visual Studio Code zainstaluj najnowszą wersję rozszerzenia usługi Azure IoT Hub dla programu Visual Studio Code.

2. Otwórz program Visual Studio Code i przejdź do karty Eksplorator i sekcji Usługi Azure IoT Hub .

3. Wybierz wielokropek (...) obok usługi Azure IoT Hub , aby wyświetlić podmenu. Wybierz opcję Wybierz centrum IoT Hub, aby pobrać centrum IoT z platformy Azure.

   W oknie podręcznym, które zostanie wyświetlone w górnej części programu Visual Studio Code, możesz wybrać subskrypcję i centrum IoT Hub.

   Zobacz pokaz na stronie usługi GitHub vscode-azure-iot-toolkit .

4. Rozwiń urządzenie w obszarze Urządzenia. Kliknij prawym przyciskiem myszy ustawienie rozproszonego śledzenia (wersja zapoznawcza), a następnie wybierz pozycję Aktualizuj ustawienie rozproszonego śledzenia (wersja zapoznawcza).

5. W okienku podręcznym wyświetlonym w górnej części okna wybierz pozycję Włącz.

   

   Włącz śledzenie rozproszone: włączone jest teraz wyświetlane w obszarze Ustawienie rozproszonego śledzenia (wersja zapoznawcza)>Żądane.

6. W okienku podręcznym wyświetlanym dla częstotliwości próbkowania wprowadź liczbę całkowitą z zakresu od 0 do 100, a następnie wybierz Enter.

   

   Częstotliwość próbkowania: 100(%) jest teraz wyświetlane w obszarze Ustawienia rozproszonego śledzenia (wersja zapoznawcza)>Żądane.

Zbiorcze aktualizowanie wielu urządzeń

Aby zaktualizować konfigurację próbkowania śledzenia rozproszonego dla wielu urządzeń, użyj automatycznej konfiguracji urządzenia. Postępuj zgodnie ze schematem bliźniaczej reprezentacji:

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

Nazwa elementu	Wymagania	Type	Opis
sampling_mode	Tak	Integer	Obecnie obsługiwane są dwie wartości trybu, aby włączyć i wyłączyć próbkowanie. 1 jest włączona i 2 jest wyłączona.
sampling_rate	Tak	Integer	Ta wartość jest wartością procentową. Dozwolone są tylko wartości z 0 do 100 (włącznie).

Wykonywanie zapytań i wizualizowanie śladów

Aby wyświetlić wszystkie ślady zarejestrowane przez centrum IoT, wykonaj zapytanie dotyczące magazynu dzienników wybranego w ustawieniach diagnostycznych. W tej sekcji przedstawiono sposób wykonywania zapytań przy użyciu usługi Log Analytics.

Jeśli skonfigurujesz usługę Log Analytics z dziennikami zasobów, wykonaj zapytanie, wyszukując dzienniki w DistributedTracing kategorii. Na przykład to zapytanie pokazuje wszystkie zarejestrowane ślady:

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

Oto kilka przykładowych dzienników w usłudze Log Analytics:

Generowane na podstawie czasu	Nazwa operacji	Kategoria	Poziom	Identyfikator korelacji	Czas trwania w milisekundach	Właściwości
2018-02-22T03:28:28.633Z	DiagnosticIoTHubD2C	Rozproszonatracing	Informacyjny	00-8cd869a412459a25f5b4f3131223344-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	Rozproszonatracing	Informacyjny	00-8cd869a412459a25f5b4f313122344-349810a9bbd28730-01	20	{"isRoutingEnabled":"false","parentSpanId":"0144d2590aacd909"}
2018-02-22T03:28:48.633Z	DiagnosticIoTHubEgress	Rozproszonatracing	Informacyjny	00-8cd869a412459a25f5b4f313122344-349810a9bbd28730-01	23	{"endpointType":"EventHub","endpointName":"myEventHub", "parentSpanId":"0144d2590aacd909"}

Aby zrozumieć typy dzienników, zobacz Dzienniki rozproszonego śledzenia usługi Azure IoT Hub.

Uruchamianie przykładowej aplikacji

W tej sekcji przygotujesz środowisko programistyczne do użycia z zestawem SDK języka C usługi Azure IoT. Następnie zmodyfikujesz jeden z przykładów, aby włączyć śledzenie rozproszone na komunikatach telemetrycznych urządzenia.

Te instrukcje dotyczą tworzenia przykładu w systemie Windows. W przypadku innych środowisk zobacz Kompilowanie zestawu C SDK lub wstępnie spakowanego zestawu C SDK na potrzeby programowania specyficznego dla platformy.

Klonowanie kodu źródłowego i inicjowanie

1. Zainstaluj pakiet roboczy Programowanie aplikacji klasycznych przy użyciu języka C++ dla programu Visual Studio 2022. Program Visual Studio 2019 jest również obsługiwany.

2. Zainstaluj narzędzie CMake. Upewnij się, że znajduje się on w twoim PATH pliku, wprowadzając polecenie cmake -version z wiersza polecenia.

3. Otwórz wiersz polecenia lub powłokę Git Bash. Uruchom następujące polecenia, aby sklonować najnowszą wersję publicznej gałęzi repozytorium GitHub zestawu SDK języka C usługi Azure IoT:

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

   Spodziewaj się, że wykonanie tej operacji potrwa kilka minut.

4. Uruchom następujące polecenia z katalogu, azure-iot-sdk-c aby utworzyć cmake podkatalog i przejść do cmake folderu:

   mkdir cmake
   cd cmake
   cmake ..
   

   Jeśli narzędzie CMake nie może znaleźć kompilatora języka C++, mogą wystąpić błędy kompilacji podczas uruchamiania poprzedniego polecenia. W takim przypadku spróbuj uruchomić polecenie w wierszu polecenia programu Visual Studio.

   Po pomyślnym zakończeniu kompilacji ostatnie kilka wierszy wyjściowych będzie wyglądać podobnie do następujących danych wyjściowych:

   $ 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
   

Edytowanie przykładu telemetrii w celu włączenia śledzenia rozproszonego

W tej sekcji edytujesz przykład iothub_ll_telemetry_sample.c w repozytorium zestawu SDK, aby włączyć śledzenie rozproszone. Możesz też skopiować już edytowaną wersję przykładu z repozytorium azure-iot-distributed-tracing-sample .

1. Użyj edytora azure-iot-sdk-c/iothub_client/samples/iothub_ll_telemetry_sample/iothub_ll_telemetry_sample.c , aby otworzyć plik źródłowy.

2. Znajdź deklarację stałej 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;
   

   Zastąp wartość stałej connectionString parametry połączenia urządzenia zapisaną w sekcji Rejestrowanie urządzenia w przewodniku Szybki start na potrzeby wysyłania danych telemetrycznych.

3. Znajdź wiersz kodu, który wywołuje IoTHubDeviceClient_LL_SetConnectionStatusCallback funkcję w celu zarejestrowania funkcji wywołania zwrotnego stanu połączenia przed pętlą wysyłania komunikatów. Dodaj kod w tym wierszu, aby wywołać IoTHubDeviceClient_LL_EnablePolicyConfiguration i włączyć śledzenie rozproszone dla urządzenia:

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

   Funkcja IoTHubDeviceClient_LL_EnablePolicyConfiguration umożliwia zasady dla określonych funkcji usługi IoT Hub skonfigurowanych za pośrednictwem bliźniaczych reprezentacji urządzeń. Po włączeniu POLICY_CONFIGURATION_DISTRIBUTED_TRACING przy użyciu dodatkowego wiersza kodu zachowanie śledzenia urządzenia będzie odzwierciedlać zmiany śledzenia rozproszonego wprowadzone na bliźniaczej reprezentacji urządzenia.

4. Aby zachować uruchamianie przykładowej aplikacji bez użycia całego limitu przydziału, dodaj jednosekundowe opóźnienie na końcu pętli komunikatów wysyłania:

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

Kompilowanie i uruchamianie

1. Przejdź do iothub_ll_telemetry_sample katalogu projektu z katalogu CMake (azure-iot-sdk-c/cmake), który został utworzony wcześniej, i skompiluj przykład:

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

2. Uruchom aplikację. Urządzenie wysyła dane telemetryczne obsługujące śledzenie rozproszone.

   Debug/iothub_ll_telemetry_sample.exe
   

3. Zachowaj działanie aplikacji. Komunikaty wysyłane do usługi IoT Hub można obserwować w oknie konsoli.

W przypadku aplikacji klienckiej, która może odbierać decyzje dotyczące próbkowania z chmury, wypróbuj przykład iothub_devicetwin_sample.c w repozytorium przykładu z przykładowym śledzeniem rozproszonym.

Obejście dla klientów innych niż Microsoft

Implementowanie funkcji śledzenia rozproszonego bez korzystania z zestawu SDK języka C jest bardziej złożone. Nie zalecamy tego.

Najpierw należy zaimplementować wszystkie typy pierwotne protokołu usługi IoT Hub w komunikatach, postępując zgodnie z przewodnikiem dewelopera Tworzenie i odczytywanie komunikatów usługi IoT Hub. Następnie zmodyfikuj właściwości protokołu w komunikatach MQTT i AMQP, aby dodać tracestate je jako właściwość systemową.

Szczególnie:

• W przypadku protokołu MQTT dodaj %24.tracestate=timestamp%3d1539243209 do tematu komunikatu. Zastąp 1539243209 element czasem tworzenia komunikatu w formacie sygnatury czasowej systemu Unix. Na przykład zapoznaj się z implementacją w zestawie SDK języka C.
• W przypadku protokołu AMQP dodaj key("tracestate") adnotację komunikatów i value("timestamp=1539243209") jako adnotację. Aby zapoznać się z implementacją referencyjną, zobacz plik uamqp_messaging.c .

Aby kontrolować procent komunikatów zawierających tę właściwość, zaimplementuj logikę w celu nasłuchiwania zdarzeń inicjowanych przez chmurę, takich jak aktualizacje bliźniaczych reprezentacji.

Następne kroki

• Aby dowiedzieć się więcej na temat ogólnego wzorca śledzenia rozproszonego w mikrousługach, zobacz Wzorzec architektury mikrousług: śledzenie rozproszone.