Tracciare i messaggi da un dispositivo al cloud di Azure IoT con la traccia distribuita (anteprima)

Articolo
07/01/2024

Usare la traccia distribuita (anteprima) nell'hub IoT per monitorare i messaggi IoT man mano che passano attraverso i servizi di Azure. L'hub IoT è uno dei primi servizi di Azure che supporta la traccia distribuita. Man mano che più servizi di Azure supporteranno la traccia distribuita, sarà possibile tracciare i messaggi Internet delle cose (IoT) nei servizi di Azure coinvolti in una soluzione. Per altre informazioni sulla funzionalità, vedere Che cos'è la traccia distribuita?.

Quando si abilita la traccia distribuita per l'hub IoT, è possibile:

Monitorare il flusso di ogni messaggio tramite l'hub IoT usando il contesto di traccia. Questo contesto di traccia include gli ID di correlazione, che consentono di correlare gli eventi di un componente con gli eventi di un altro componente. È possibile applicarlo per un subset o per tutti i messaggi del dispositivo IoT usando un dispositivo gemello.
Registrare il contesto di traccia per Log di Monitoraggio di Azure.
Misurare e comprendere il flusso e la latenza dei messaggi dai dispositivi all'hub IoT e agli endpoint di routing.

Importante

La traccia distribuita di un hub IoT di Azure è attualmente disponibile in ANTEPRIMA. Vedere le condizioni per l'utilizzo supplementari per le anteprime di Microsoft Azure per termini legali aggiuntivi che si applicano a funzionalità di Azure in versione beta, in anteprima o in altro modo non ancora disponibili a livello generale.

Prerequisiti

Un hub IoT di Azure creato in una delle aree seguenti.
- Europa settentrionale
- Asia sud-orientale
- West US 2
Un dispositivo registrato nell'hub IoT. Se non si ha un dispositivo nell'hub IoT, seguire i passaggi descritti in Registrare un dispositivo e salvare la stringa di connessione del dispositivo da usare in questo articolo.
Questo articolo presuppone che si abbia familiarità con l'invio di messaggi di telemetria a un hub IoT.
Ultima versione di Git.

Anteprima pubblica - Limiti e considerazioni

Prendere in considerazione le limitazioni seguenti per determinare se questa funzionalità di anteprima è adatta agli scenari:

La proposta per lo standard del contesto di traccia W3C è attualmente allo stato di bozza.
L'unico linguaggio di sviluppo attualmente supportato dall'SDK client è C, nel ramo di anteprima pubblica di Azure IoT SDK per dispositivi per C
La funzionalità da cloud a dispositivo gemello non è disponibile per il livello Basic dell'hub IoT. L'hub IoT tuttavia accederà comunque a Monitoraggio di Azure se rileva un'intestazione del contesto di traccia composta in modo corretto.
Per garantire un funzionamento efficiente, l'hub IoT imporrà una limitazione alla frequenza di registrazione che può essere eseguita nell'ambito della traccia distribuita.
La funzionalità di traccia distribuita è supportata solo per gli hub IoT creati nelle aree seguenti:
- Europa settentrionale
- Asia sud-orientale
- West US 2

Informazioni sulla traccia distribuita di Azure IoT

Molte soluzioni IoT, tra cui l'architettura di riferimento di Azure IoT, in genere seguono una variante dell'architettura di microservizi, Man mano che una soluzione IoT diventa più complessa, si accumula una dozzina o più di microservizi, non tutti necessariamente di Azure.

L'individuazione delle posizioni in cui i messaggi IoT vengono eliminati o rallentano può risultare complicata. Si supponga ad esempio di disporre di una soluzione IoT che usa cinque diversi servizi di Azure e 1.500 dispositivi attivi. Ogni dispositivo invia 10 messaggi da dispositivo a cloud al secondo, per un totale di 15.000 messaggi al secondo. Si noti tuttavia che l'app Web vede solo 10.000 messaggi al secondo. Come è possibile individuarne la causa?

Per ricostruire il flusso di un messaggio IoT attraverso i servizi, ogni servizio deve propagare un ID di correlazione che identifichi in modo univoco il messaggio. Dopo che Monitoraggio di Azure raccoglie gli ID di correlazione in un sistema centralizzato, è possibile usare tali ID per visualizzare il flusso dei messaggi. Questo metodo è denominato modello di traccia distribuita.

Per supportare una più ampia adozione della traccia distribuita, Microsoft sta contribuendo alla proposta dello standard W3C per la traccia distribuita. Quando è abilitato il supporto della traccia distribuita per l'hub IoT, segue questo flusso per ogni messaggio generato:

Viene generato un messaggio nel dispositivo IoT.
Il dispositivo IoT decide (con l'aiuto del cloud) che il messaggio deve essere assegnato con un contesto di traccia.
L'SDK aggiunge un valore tracestate alla proprietà del messaggio, che contiene il timestamp per la creazione del messaggio.
Il dispositivo IoT invia il messaggio all'hub IoT.
Il messaggio arriva al gateway dell'hub IoT.
L'hub IoT cerca il valore tracestate nelle proprietà del messaggio e verifica se è nel formato corretto. In tal caso, l'hub IoT genera un valore trace-id univoco globale per il messaggio e un valore span-id per l'hop. L'hub IoT registra questi valori nei log di traccia distribuiti dell'hub IoT nell'operazione DiagnosticIoTHubD2C.
Al termine dell'elaborazione dei messaggi, l'hub IoT genera un altro valore span-id e lo registra, insieme al valore trace-id esistente, nell'operazione di DiagnosticIoTHubIngress.
Se è abilitato il routing del messaggio, l'hub IoT lo scrive nell'endpoint personalizzato. L'hub IoT registra un altro valore di span-id con lo stesso valore trace-id nella categoria DiagnosticIoTHubEgress.

Configurare la traccia distribuita in un hub IoT

In questa sezione si configurerà un hub IoT per registrare gli attributi della traccia distribuita (ID di correlazione e timestamp).

Nel portale di Azure passare all'hub IoT.
Nel riquadro sinistro dell'hub IoT scorrere verso il basso fino alla sezione Monitoraggio e selezionare Impostazioni di diagnostica.
Selezionare Aggiungi impostazione di diagnostica.
Nella casella Nome dell'impostazione di diagnostica immettere un nome per una nuova impostazione di diagnostica. Ad esempio immettere DistributedTracingSettings.
Scegliere una o più delle opzioni seguenti in Dettagli destinazione per determinare dove inviare le informazioni di registrazione:
- Archiviare in un account di archiviazione: configurare un account di archiviazione che deve contenere le informazioni di registrazione.
- Stream a un hub eventi: configurare un hub eventi che deve contenere le informazioni di registrazione.
- Invia a Log Analytics: configurare un'area di lavoro Log Analytics che deve contenere le informazioni di registrazione.
Nella sezione Log selezionare le operazioni da registrare.

Includere Traccia distribuita e configurare un periodo di Conservazione per i giorni per cui si vuole conservare la registrazione. Il periodo di conservazione dei log ha effetto sui costi di archiviazione.
Seleziona Salva.
(Facoltativo) Per visualizzare il flusso di messaggi per destinazioni diverse, configurare regole di gestione per almeno due endpoint diversi.

Dopo l'attivazione della registrazione, l'hub IoT registra un log quando viene rilevato un messaggio contenente proprietà di traccia valide in una delle situazioni seguenti:

Il messaggio arriva al gateway dell'hub IoT.
L'hub IoT elabora il messaggio.
Il messaggio viene indirizzato a endpoint personalizzati. Il routing deve essere abilitato.

Per altre informazioni su questi log e sui relativi schemi, vedere Monitorare l'hub IoT e Traccia distribuita nei log delle risorse dell'hub IoT.

Aggiornare le opzioni di campionamento

Per modificare la percentuale di messaggi da tracciare dal cloud, è necessario aggiornare il dispositivo gemello. È possibile eseguire gli aggiornamenti usando l'editor JSON nel portale di Azure o nell'SDK del servizio hub IoT. Per gli esempi, vedere le sottosezioni seguenti.

Aggiornare un singolo dispositivo

È possibile usare il portale di Azure o l'estensione hub IoT di Azure per Visual Studio Code (VS Code) per aggiornare la frequenza di campionamento di un singolo dispositivo.

Azure portal
VS Code

Passare all'hub IoT nel portale di Azuree quindi selezionare Dispositivi nella sezione Gestione dei dispositivi del menu.
Scegliere il dispositivo.
Selezionare l'icona a forma di ingranaggio in Traccia distribuita (anteprima). Nel pannello che si apre:
1. Selezionare l'opzione Abilita.
2. Per Frequenza di campionamento, scegliere una percentuale compresa tra 0 e 100.
3. Seleziona Salva.
Attendere alcuni secondi e selezionare Aggiorna. Se il dispositivo riconosce correttamente le modifiche, viene visualizzata un'icona di sincronizzazione con un segno di spunta.

Eseguire l'aggiornamento in blocco per più dispositivi

Per aggiornare la configurazione di campionamento della traccia distribuita per più dispositivi, usare la configurazione automatica dei dispositivi. Seguire questo schema per dispositivi gemelli:

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

Nome dell'elemento	Obbligatorio	Type	Descrizione
`sampling_mode`	Sì	Intero	Sono attualmente supportati i valori di due modalità per attivare e disattivare il campionamento. `1` per attivare e `2` per disattivare.
`sampling_rate`	Sì	Intero	Questo valore indica una percentuale. Sono consentiti solo valori compresi tra `0` e `100` (estremi inclusi).

Eseguire una query e visualizzare le tracce

Per visualizzare tutte le tracce registrate da un hub IoT, eseguire una query sull'archivio dei log selezionato nelle impostazioni di diagnostica. Questa sezione illustra come eseguire query usando Log Analytics.

Se è stata eseguita la configurazione di Log Analytics con i log delle risorse, eseguire una query cercando i log nella categoria DistributedTracing. Questa query ad esempio mostra tutte le tracce registrate:

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

Ecco alcuni log di esempio in Log Analytics:

Generato in base al tempo	Nome operazione	Categoria	Level	ID correlazione	Durata in millisecondi	Proprietà
2018-02-22T03:28:28.633Z	DiagnosticIoTHubD2C	DistributedTracing	Informazioni	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	Informazioni	00-8cd869a412459a25f5b4f31311223344-349810a9bbd28730-01	20	`{"isRoutingEnabled":"false","parentSpanId":"0144d2590aacd909"}`
2018-02-22T03:28:48.633Z	DiagnosticIoTHubEgress	DistributedTracing	Informazioni	00-8cd869a412459a25f5b4f31311223344-349810a9bbd28730-01	23	`{"endpointType":"EventHub","endpointName":"myEventHub", "parentSpanId":"0144d2590aacd909"}`

Per informazioni sui tipi di log, vedere Log di traccia distribuiti dell'hub IoT di Azure.

Eseguire un'applicazione di esempio

In questa sezione si preparerà un ambiente di sviluppo da usare con Azure IoT SDK per C. Si modificherà quindi uno degli esempi per abilitare la traccia distribuita nei messaggi di telemetria del dispositivo.

Queste istruzioni sono relative alla compilazione dell'esempio in Windows. Per altri ambienti, vedere Compile the C SDK (Compilare l'SDK per C) oppure Prepackaged C SDK for Platform Specific Development (Pacchetto SDK per C per lo sviluppo specifico della piattaforma).

Clonare il codice sorgente ed eseguire l'inizializzazione

Installare il carico di lavoro Sviluppo di applicazioni desktop con C++ per Visual Studio 2022. È supportato anche Visual Studio 2019.
Installare CMake. Assicurarsi che si trovi inPATH immettendo cmake -version da un prompt dei comandi.
Aprire un prompt dei comandi o la shell Git Bash. Eseguire i comandi seguenti per clonare la versione più recente del ramo di anteprima pubblica del repository GitHub 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
```
Il completamento di questa operazione richiederà alcuni minuti.
Eseguire i comandi seguenti dalla directory azure-iot-sdk-c per creare una sottodirectory cmake e passare alla cartella cmake:
```
mkdir cmake
cd cmake
cmake ..
```
Se CMake non riesce a trovare il compilatore C++, potrebbero verificarsi errori di compilazione durante l'esecuzione del comando precedente. In tal caso, provare a eseguire il comando nel prompt dei comandi di Visual Studio.

Al termine della compilazione, le ultime righe di output saranno simili all'output seguente:
```
$ 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
```

Modificare l'esempio dei dati di telemetria per abilitare la traccia distribuita

In questa sezione si modifica l'esempio di iothub_ll_telemetry_sample.c nel repository SDK per abilitare la traccia distribuita. In alternativa, è possibile copiare una versione già modificata dell'esempio dal repository azure-iot-distributed-tracing-sample.

Usare un editor per aprire il file di origine azure-iot-sdk-c/iothub_client/samples/iothub_ll_telemetry_sample/iothub_ll_telemetry_sample.c.
Individuare la dichiarazione della costante 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;
```
Sostituire il valore della costante connectionString con la stringa di connessione del dispositivo salvata nella sezione Registrare un dispositivo della guida introduttiva per l'invio dei dati di telemetria.
Trovare la riga di codice che chiama IoTHubDeviceClient_LL_SetConnectionStatusCallback per registrare una funzione di callback dello stato di connessione prima del ciclo di messaggi di invio. Aggiungere il codice sotto tale riga per chiamare IoTHubDeviceClient_LL_EnablePolicyConfiguration abilitando la traccia distribuita per il dispositivo:
```
// 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)
```
La funzione IoTHubDeviceClient_LL_EnablePolicyConfiguration abilita i criteri per specifiche funzionalità dell'hub IoT configurate tramite dispositivi gemelli. Dopo l'abilitazione di POLICY_CONFIGURATION_DISTRIBUTED_TRACING con la riga di codice aggiuntiva, il comportamento della traccia del dispositivo rifletterà le modifiche della traccia distribuita apportate nel dispositivo gemello.

Per mantenere l'app di esempio in esecuzione senza usare tutta la quota, aggiungere un ritardo di un secondo alla fine del ciclo di messaggi di invio:

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

Compila ed esegui

Passare alla directory del progetto iothub_ll_telemetry_sample dalla directory CMake (azure-iot-sdk-c/cmake) creata in precedenza e compilare l'esempio:
```
cd iothub_client/samples/iothub_ll_telemetry_sample
cmake --build . --target iothub_ll_telemetry_sample --config Debug
```
Eseguire l'applicazione. Il dispositivo invierà i dati di telemetria che supportano la traccia distribuita.
```
Debug/iothub_ll_telemetry_sample.exe
```
Mantenere l'app in esecuzione. È possibile osservare i messaggi inviati all'hub IoT nella finestra della console.

Per un'app client in grado di ricevere decisioni di campionamento dal cloud, provare l'esempio iothub_devicetwin_sample.c nel repository di esempio di traccia distribuita.

Soluzione alternativa per i client non Microsoft

L'implementazione della funzionalità di traccia distribuita senza usare l'SDK C è più complessa, ma non è una scelta consigliata.

Prima di tutto, è necessario implementare tutte le primitive del protocollo dell'hub IoT nei messaggi seguendo la guida per gli sviluppatori Creare e leggere i messaggi dell'hub IoT. Quindi, modificare le proprietà del protocollo nei messaggi MQTT e AMQP per aggiungere tracestate come proprietà di sistema.

In particolare:

Per MQTT aggiungere %24.tracestate=timestamp%3d1539243209 all'argomento del messaggio. Sostituire 1539243209 con l'ora di creazione del messaggio in formato timestamp Unix. Ad esempio, fare riferimento all'implementazione in C SDK.
Per AMQP, aggiungere key("tracestate") e value("timestamp=1539243209") come annotazione del messaggio. Per un'implementazione di riferimento, vedere il file uamqp_messaging.c.

Per controllare la percentuale di messaggi con questa proprietà, implementare la logica per l'ascolto di eventi avviati dal cloud, ad esempio aggiornamenti di dispositivi gemelli.

Passaggi successivi

Per altre informazioni sul modello di traccia distribuita generale nei microservizi, vedere Microservice architecture pattern: distributed tracing (Modello di architettura di microservizi: traccia distribuita).

Condividi tramite