Tracciare i messaggi da dispositivo a cloud di Azure IoT usando la traccia distribuita (anteprima)

Articolo
04/07/2024

Usare la traccia distribuita (anteprima) in hub IoT per monitorare i messaggi IoT mentre passano attraverso i servizi di Azure. L'hub IoT è uno dei primi servizi di Azure che supporta la traccia distribuita. Man mano che altri servizi di Azure supportano la traccia distribuita, è possibile tracciare i messaggi Internet delle cose (IoT) in tutti i servizi di Azure coinvolti nella soluzione. Per altre informazioni sulla funzionalità, vedere Che cos'è la traccia distribuita?.

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

Monitorare il flusso di ogni messaggio attraverso hub IoT usando il contesto di traccia. Il contesto di traccia include ID di correlazione che consentono di correlare eventi da un componente con 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 nei 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 è disponibile, seguire la procedura descritta in Registrare un nuovo dispositivo nell'hub IoT e salvare il dispositivo stringa di connessione da usare in questo articolo.
Questo articolo presuppone che si abbia familiarità con l'invio di messaggi di telemetria a un hub IoT.
Versione più recente 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 W3C Trace Context è attualmente una bozza funzionante.
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à del dispositivo gemello da cloud a dispositivo non è disponibile per il livello basic hub IoT. Tuttavia, hub IoT ancora log in Monitoraggio di Azure se rileva un'intestazione di contesto di traccia composta correttamente.
Per garantire un'operazione efficiente, hub IoT impone una limitazione sulla velocità di registrazione che può verificarsi come parte 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, inclusa l'architettura di riferimento di Azure IoT, seguono in genere una variante dell'architettura del microservizio. Man mano che una soluzione IoT diventa più complessa, si accumula una dozzina o più di microservizi, Questi microservizi potrebbero essere o meno provenienti da Azure.

L'individuazione dei messaggi IoT da eliminare o rallentare può risultare complessa. Si supponga, ad esempio, di avere 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 tra i servizi, ogni servizio deve propagare un ID di correlazione che identifica 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 hub IoT, segue questo flusso per ogni messaggio generato:

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

Configurare la traccia distribuita in un hub IoT

In questa sezione viene configurato un hub IoT per registrare gli attributi di traccia distribuita (ID di correlazione e timestamp).

Passare all'hub IoT nell'portale di Azure.
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 impostazione diagnostica immettere un nome per una nuova impostazione di diagnostica. Ad esempio, immettere DistributedTracing Impostazioni.
Scegliere una o più delle opzioni seguenti in Dettagli destinazione per determinare dove inviare le informazioni di registrazione:
- Archivio in un account di archiviazione: configurare un account di archiviazione in modo da contenere le informazioni di registrazione.
- Trasmettere a un hub eventi: configurare un hub eventi per contenere le informazioni di registrazione.
- Invia a Log Analytics: configurare un'area di lavoro Log Analytics per contenere le informazioni di registrazione.
Nella sezione Log selezionare le operazioni da registrare.

Includere La traccia distribuita e configurare un periodo di conservazione per il numero di giorni di conservazione della registrazione. La conservazione dei log influisce 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, 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 hub IoT e Traccia distribuita nei log delle risorse 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 nella portale di Azure e 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 quindi selezionare Aggiorna. Se il dispositivo riconosce correttamente le modifiche, viene visualizzata un'icona di sincronizzazione con un segno di spunta.

Aggiornare in blocco più dispositivi

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

{
    "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` è acceso, ed `2` è spento.
`sampling_rate`	Sì	Intero	Questo valore indica una percentuale. Sono consentiti solo valori compresi tra `0` e `100` (estremi inclusi).

Eseguire query e visualizzare tracce

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

Se si configura Log Analytics con i log delle risorse, eseguire una query cercando i log nella DistributedTracing categoria . Ad esempio, questa query 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	Livello	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 hub IoT di Azure log di traccia distribuiti.

Eseguire un'applicazione di esempio

In questa sezione si preparerà un ambiente di sviluppo da usare con Azure IoT SDK per C. Modificare 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 tratti di PATH un'avvio 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
```
Attendere il completamento di questa operazione per alcuni minuti.
Eseguire i comandi seguenti dalla azure-iot-sdk-c directory per creare una cmake sottodirectory e passare alla cmake cartella :
```
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 di telemetria per abilitare la traccia distribuita

In questa sezione si modifica l'esempio 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 connectionString costante con il dispositivo stringa di connessione salvato 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 codice sotto tale riga per chiamare IoTHubDeviceClient_LL_EnablePolicyConfiguration e abilitare 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 IoTHubDeviceClient_LL_EnablePolicyConfiguration funzione abilita i criteri per funzionalità di hub IoT specifiche configurate tramite dispositivi gemelli. Dopo l'abilitazione POLICY_CONFIGURATION_DISTRIBUTED_TRACING tramite la riga di codice aggiuntiva, il comportamento di traccia del dispositivo rifletterà le modifiche alla 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 iothub_ll_telemetry_sample progetto 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 invia dati di telemetria che supportano la traccia distribuita.
```
Debug/iothub_ll_telemetry_sample.exe
```
Mantenere l'app in esecuzione. È possibile osservare i messaggi inviati a 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 C SDK è più complessa. Non è consigliabile.

Prima di tutto, è necessario implementare tutte le primitive del protocollo hub IoT nei messaggi seguendo la guida per sviluppatori Creare e leggere hub IoT messaggi. Modificare quindi le proprietà del protocollo nei messaggi MQTT e AMQP da 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 che contengono questa proprietà, implementare la logica per ascoltare gli eventi avviati dal cloud, ad esempio gli aggiornamenti dei 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).