Monitoraggio delle operazioni dell'hub IoTIoT Hub operations monitoring

Il monitoraggio delle operazioni dell'hub IoT consente di monitorare lo stato delle operazioni nel proprio hub IoT in tempo reale.IoT Hub operations monitoring enables you to monitor the status of operations on your IoT hub in real time. L'hub IoT tiene traccia degli eventi nelle diverse categorie di operazioni.IoT Hub tracks events across several categories of operations. È possibile scegliere di impostare l'invio di eventi da una o più categorie a un endpoint del proprio hub IoT per l'elaborazione.You can opt into sending events from one or more categories to an endpoint of your IoT hub for processing. È possibile monitorare i dati per individuare gli errori o configurare un'elaborazione più complessa in base ai modelli di dati.You can monitor the data for errors or set up more complex processing based on data patterns.

Nota

Il monitoraggio operazioni dell'hub IoT è deprecato e verrà rimosso nelle versioni future dell'hub IoT.IoT Hub operations monitoring is deprecated and will be removed from IoT Hub in the future. Per monitorare le operazioni e l'integrità dell'hub IoT, vedere Monitor the health of Azure IoT Hub and diagnose problems quickly (Monitorare lo stato dell'hub IoT di Azure e diagnosticare i problemi rapidamente)For monitoring the operations and health of IoT Hub, see Monitor the health of Azure IoT Hub and diagnose problems quickly. Per altre informazioni sulla sequenza temporale relativa alla funzionalità deprecata, vedere Monitorare le soluzioni IoT di Azure con Monitoraggio di Azure e Integrità risorse di Azure.For more information about the deprecation timeline, see Monitor your Azure IoT solutions with Azure Monitor and Azure Resource Health.

L'hub IoT monitora sei categorie di eventi:IoT Hub monitors six categories of events:

  • Operazioni relative alle identità dei dispositiviDevice identity operations
  • Telemetria dei dispositiviDevice telemetry
  • Messaggi da cloud a dispositivoCloud-to-device messages
  • ConnessioniConnections
  • Caricamenti di fileFile uploads
  • Routing dei messaggiMessage routing

Importante

Il monitoraggio delle operazioni dell'hub IoT non garantisce il recapito affidabile o ordinato di eventi.IoT Hub operations monitoring does not guarantee reliable or ordered delivery of events. A seconda dell'infrastruttura sottostante dell'hub IoT alcuni eventi potrebbero essere persi o recapitati nell'ordine errato.Depending on IoT Hub underlying infrastructure, some events might be lost or delivered out of order. Usare le operazioni di monitoraggio per generare avvisi in base ai segnali di errore, ad esempio i tentativi di connessione non riuscita o disconnessioni ad alta frequenza di dispositivi specifici.Use operations monitoring to generate alerts based on error signals such as failed connection attempts, or high-frequency disconnections for specific devices. Non basarsi sulle operazioni di monitoraggio di eventi per creare un archivio coerente per lo stato del dispositivo, ad esempio un archivio che rileva lo stato di connessione o disconnessione di un dispositivo.You should not rely on operations monitoring events to create a consistent store for device state, e.g. a store tracking connected or disconnected state of a device.

Come abilitare il monitoraggio delle operazioniHow to enable operations monitoring

  1. Creare un hub IoT.Create an IoT hub. Le istruzioni sulla creazione di un hub IoT sono disponibili nella Guida introduttiva.You can find instructions on how to create an IoT hub in the Get Started guide.

  2. Aprire il pannello dell'hub IoT.Open the blade of your IoT hub. Da qui, fare clic su Monitoraggio operazioni.From there, click Operations monitoring.

    Accedere alla configurazione del monitoraggio delle operazioni nel portale

  3. Selezionare le categorie di monitoraggio da controllare e fare clic su Salva.Select the monitoring categories you wish to monitor, and then click Save. Gli eventi sono disponibili per la lettura nell'endpoint compatibile con l'hub eventi elencato in Impostazioni di monitoraggio.The events are available for reading from the Event Hub-compatible endpoint listed in Monitoring settings. L'endpoint dell'hub IoT è chiamato messages/operationsmonitoringevents.The IoT Hub endpoint is called messages/operationsmonitoringevents.

    Configurare il monitoraggio delle operazioni sull'hub IoT

Nota

La selezione del monitoraggio Dettagliato per la categoria Connessioni consente all'hub IoT di generare messaggi di diagnostica aggiuntivi.Selecting Verbose monitoring for the Connections category causes IoT Hub to generate additional diagnostics messages. Per tutte le altre categorie, l'impostazione Dettagliato modifica la quantità di informazioni che l'hub IoT include in ogni messaggio di errore.For all other categories, the Verbose setting changes the quantity of information IoT Hub includes in each error message.

Categorie di eventi e modalità d'usoEvent categories and how to use them

Ogni categoria di monitoraggio delle operazioni tiene traccia di un diverso tipo di interazione con l'hub IoT e ogni categoria di monitoraggio ha uno schema che definisce come sono strutturati gli eventi nella categoria stessa.Each operations monitoring category tracks a different type of interaction with IoT Hub, and each monitoring category has a schema that defines how events in that category are structured.

Operazioni relative alle identità dei dispositiviDevice identity operations

La categoria di operazioni di identità del dispositivo tiene traccia degli errori che si verificano quando si prova a creare, aggiornare o eliminare una voce nel registro delle identità dell'hub IoT.The device identity operations category tracks errors that occur when you attempt to create, update, or delete an entry in your IoT hub's identity registry. Il rilevamento di questa categoria è utile per gli scenari di provisioning.Tracking this category is useful for provisioning scenarios.

{
    "time": "UTC timestamp",
    "operationName": "create",
    "category": "DeviceIdentityOperations",
    "level": "Error",
    "statusCode": 4XX,
    "statusDescription": "MessageDescription",
    "deviceId": "device-ID",
    "durationMs": 1234,
    "userAgent": "userAgent",
    "sharedAccessPolicy": "accessPolicy"
}

Telemetria dei dispositiviDevice telemetry

La categoria di telemetria dei dispositivi tiene traccia degli errori che si verificano nell'hub IoT e sono correlati alla pipeline di telemetria.The device telemetry category tracks errors that occur at the IoT hub and are related to the telemetry pipeline. Questa categoria include gli errori che si verificano durante l'invio di eventi di telemetria, ad esempio la limitazione, e la ricezione di eventi di telemetria, ad esempio un lettore non autorizzato.This category includes errors that occur when sending telemetry events (such as throttling) and receiving telemetry events (such as unauthorized reader). Questa categoria non può intercettare gli errori causati da codice in esecuzione nel dispositivo stesso.This category cannot catch errors caused by code running on the device itself.

{
    "messageSizeInBytes": 1234,
    "batching": 0,
    "protocol": "Amqp",
    "authType": "{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\"}",
    "time": "UTC timestamp",
    "operationName": "ingress",
    "category": "DeviceTelemetry",
    "level": "Error",
    "statusCode": 4XX,
    "statusType": 4XX001,
    "statusDescription": "MessageDescription",
    "deviceId": "device-ID",
    "EventProcessedUtcTime": "UTC timestamp",
    "PartitionId": 1,
    "EventEnqueuedUtcTime": "UTC timestamp"
}

Comandi da cloud a dispositivoCloud-to-device commands

La categoria di comandi da cloud a dispositivo tiene traccia degli errori che si verificano nell'hub IoT e sono correlati alla pipeline di messaggi da cloud a dispositivo.The cloud-to-device commands category tracks errors that occur at the IoT hub and are related to the cloud-to-device message pipeline. Questa categoria include gli errori che si verificano durante l'invio di messaggi da cloud a dispositivo, ad esempio un mittente non autorizzato, la ricezione di messaggi da cloud a dispositivo, ad esempio il superamento del numero di recapiti, e la ricezione di commenti sui messaggi da cloud a dispositivo, ad esempio commenti scaduti.This category includes errors that occur when sending cloud-to-device messages (such as unauthorized sender), receiving cloud-to-device messages (such as delivery count exceeded), and receiving cloud-to-device message feedback (such as feedback expired). Questa categoria non intercetta gli errori da un dispositivo che gestisce in modo non corretto un messaggio da cloud a dispositivo, se questo è stato recapitato correttamente.This category does not catch errors from a device that improperly handles a cloud-to-device message if the cloud-to-device message was delivered successfully.

{
    "messageSizeInBytes": 1234,
    "authType": "{\"scope\":\"hub\",\"type\":\"sas\",\"issuer\":\"iothub\"}",
    "deliveryAcknowledgement": 0,
    "protocol": "Amqp",
    "time": " UTC timestamp",
    "operationName": "ingress",
    "category": "C2DCommands",
    "level": "Error",
    "statusCode": 4XX,
    "statusType": 4XX001,
    "statusDescription": "MessageDescription",
    "deviceId": "device-ID",
    "EventProcessedUtcTime": "UTC timestamp",
    "PartitionId": 1,
    "EventEnqueuedUtcTime": "UTC timestamp"
}

ConnessioniConnections

La categoria Connessioni tiene traccia degli errori che si verificano quando i dispositivi si connettono o disconnettono da un hub IoT.The connections category tracks errors that occur when devices connect or disconnect from an IoT hub. Il rilevamento di questa categoria è utile per identificare i tentativi di connessione non autorizzati e per rilevare quando una connessione viene persa dai dispositivi in aree di scarsa connettività.Tracking this category is useful for identifying unauthorized connection attempts and for tracking when a connection is lost for devices in areas of poor connectivity.

{
    "durationMs": 1234,
    "authType": "{\"scope\":\"hub\",\"type\":\"sas\",\"issuer\":\"iothub\"}",
    "protocol": "Amqp",
    "time": " UTC timestamp",
    "operationName": "deviceConnect",
    "category": "Connections",
    "level": "Error",
    "statusCode": 4XX,
    "statusType": 4XX001,
    "statusDescription": "MessageDescription",
    "deviceId": "device-ID"
}

Caricamenti di fileFile uploads

La categoria di caricamenti dei file tiene traccia degli errori che si verificano nell'hub IoT e correlati alla funzionalità di caricamento dei file.The file upload category tracks errors that occur at the IoT hub and are related to file upload functionality. Questa categoria include:This category includes:

  • Errori che si verificano con l'URI di firma di accesso condiviso, ad esempio quando l'URI scade prima che un dispositivo notifichi all'hub un caricamento completato.Errors that occur with the SAS URI, such as when it expires before a device notifies the hub of a completed upload.
  • Caricamenti non riusciti segnalati dal dispositivo.Failed uploads reported by the device.
  • Errori che si verificano quando un file non viene trovato nell'archivio durante la creazione del messaggio di notifica dell'hub IoT.Errors that occur when a file is not found in storage during IoT Hub notification message creation.

Questa categoria non può intercettare errori che si verificano direttamente mentre il dispositivo sta caricando un file in memoria.This category cannot catch errors that directly occur while the device is uploading a file to storage.

{
    "authType": "{\"scope\":\"hub\",\"type\":\"sas\",\"issuer\":\"iothub\"}",
    "protocol": "HTTP",
    "time": " UTC timestamp",
    "operationName": "ingress",
    "category": "fileUpload",
    "level": "Error",
    "statusCode": 4XX,
    "statusType": 4XX001,
    "statusDescription": "MessageDescription",
    "deviceId": "device-ID",
    "blobUri": "http//bloburi.com",
    "durationMs": 1234
}

Routing dei messaggiMessage routing

La categoria del routing dei messaggi tiene traccia degli errori che si verificano durante la valutazione del routing dei messaggi e dell'integrità dell'endpoint percepiti dall'hub IoT.The message routing category tracks errors that occur during message route evaluation and endpoint health as perceived by IoT Hub. Questa categoria include eventi come ad esempio quando una regola viene valutata come "non definita", quando l'hub IoT contrassegna un endpoint come inattivo ed eventuali altri errori ricevuti da un endpoint.This category includes events such as when a rule evaluates to "undefined", when IoT Hub marks an endpoint as dead, and any other errors received from an endpoint. Questa categoria non include errori specifici sui messaggi stessi, ad esempio gli errori di limitazione sui dispositivi, che vengono segnalati nella categoria "telemetria del dispositivo".This category does not include specific errors about the messages themselves (such as device throttling errors), which are reported under the "device telemetry" category.

{
    "messageSizeInBytes": 1234,
    "time": "UTC timestamp",
    "operationName": "ingress",
    "category": "routes",
    "level": "Error",
    "deviceId": "device-ID",
    "messageId": "ID of message",
    "routeName": "myroute",
    "endpointName": "myendpoint",
    "details": "ExternalEndpointDisabled"
}

Visualizzare eventiView events

È possibile usare lo strumento iothub-explorer per verificare rapidamente che l'hub IoT stia generando eventi di monitoraggio.You can use the iothub-explorer tool to quickly test that your IoT hub is generating monitoring events. Per installare lo strumento, vedere le istruzioni disponibili nel repository GitHub iothub-explorer.To install the tool, see the instructions in the iothub-explorer GitHub repository.

  1. Assicurarsi che la categoria di monitoraggio Connessioni sia impostata su Dettagliato nel portale.Make sure the Connections monitoring category is set to Verbose in the portal.

  2. Al prompt dei comandi eseguire il comando seguente per consentire la lettura dell'endpoint di monitoraggio:At a command-prompt, run the following command to read from the monitoring endpoint:

    iothub-explorer monitor-ops --login {your iothubowner connection string}
    
  3. A un altro prompt dei comandi eseguire il comando seguente per simulare un dispositivo che invia messaggi da dispositivo a cloud:In another command-prompt, run the following command to simulate a device sending device-to-cloud messages:

    iothub-explorer simulate-device {your device name} --send "My test message" --login {your iothubowner connection string}
    
  4. Il primo prompt dei comandi visualizza gli eventi di monitoraggio nel momento in cui il dispositivo simulato si connette all'hub IoT.The first command-prompt shows the monitoring events as the simulated device connects to your IoT hub.

Connettersi all'endpoint di monitoraggioConnect to the monitoring endpoint

L'endpoint di monitoraggio sull'hub IoT è un endpoint compatibile con Hub eventi.The monitoring endpoint on your IoT hub is an Event Hub-compatible endpoint. Per leggere i messaggi di monitoraggio da questo endpoint, è possibile usare qualsiasi meccanismo che funzioni con l'Hub eventi.You can use any mechanism that works with Event Hubs to read monitoring messages from this endpoint. L'esempio seguente crea un lettore di base non adatto per una distribuzione con velocità effettiva elevata.The following sample creates a basic reader that is not suitable for a high throughput deployment. Per altre informazioni su come elaborare i messaggi da Hub eventi, vedere l'esercitazione Introduzione all'Hub eventi.For more information about how to process messages from Event Hubs, see the Get Started with Event Hubs tutorial.

Per connettersi all'endpoint di monitoraggio, è necessaria una stringa di connessione e il nome dell'endpoint.To connect to the monitoring endpoint, you need a connection string and the endpoint name. La procedura seguente mostra come trovare i valori necessari nel portale:The following steps show you how to find the necessary values in the portal:

  1. Nel portale, passare al pannello di risorse dell'hub IoT.In the portal, navigate to your IoT Hub resource blade.

  2. Scegliere Monitoraggio operazioni e prendere nota dei valori in Nome compatibile con Hub eventi e in Endpoint compatibile con Hub eventi:Choose Operations monitoring, and make a note of the Event Hub-compatible name and Event Hub-compatible endpoint values:

    Valori di Endpoint compatibile con Hub eventi

  3. Scegliere Criteri di accesso condiviso, quindi scegliere servizio.Choose Shared access policies, then choose service. Prendere nota del valore presente in Chiave primaria:Make a note of the Primary key value:

    Chiave primaria del servizio dei criteri di accesso condiviso

L'esempio di codice C# seguente viene preso da un'app console C# per Desktop classico di Windows di Visual Studio.The following C# code sample is taken from a Visual Studio Windows Classic Desktop C# console app. Il progetto ha il pacchetto WindowsAzure.ServiceBus NuGet installato.The project has the WindowsAzure.ServiceBus NuGet package installed.

  • Sostituire il placeholder della stringa di connessione con una stringa di connessione che usa i valori precedentemente annotati per l'endpoint compatibile con Hub eventi e il servizio Chiave primaria come illustrato nell'esempio seguente:Replace the connection string placeholder with a connection string that uses the Event Hub-compatible endpoint and service Primary key values you noted previously as shown in the following example:

    "Endpoint={your Event Hub-compatible endpoint};SharedAccessKeyName=service;SharedAccessKey={your service primary key value}"
    
  • Sostituire il placeholder del nome dell'endpoint di monitoraggio con il valore del nome Hub eventi compatibile annotato in precedenza.Replace the monitoring endpoint name placeholder with the Event Hub-compatible name value you noted previously.

class Program
{
    static string connectionString = "{your monitoring endpoint connection string}";
    static string monitoringEndpointName = "{your monitoring endpoint name}";
    static EventHubClient eventHubClient;

    static void Main(string[] args)
    {
        Console.WriteLine("Monitoring. Press Enter key to exit.\n");

        eventHubClient = EventHubClient.CreateFromConnectionString(connectionString, monitoringEndpointName);
        var d2cPartitions = eventHubClient.GetRuntimeInformation().PartitionIds;
        CancellationTokenSource cts = new CancellationTokenSource();
        var tasks = new List<Task>();

        foreach (string partition in d2cPartitions)
        {
            tasks.Add(ReceiveMessagesFromDeviceAsync(partition, cts.Token));
        }

        Console.ReadLine();
        Console.WriteLine("Exiting...");
        cts.Cancel();
        Task.WaitAll(tasks.ToArray());
    }

    private static async Task ReceiveMessagesFromDeviceAsync(string partition, CancellationToken ct)
    {
        var eventHubReceiver = eventHubClient.GetDefaultConsumerGroup().CreateReceiver(partition, DateTime.UtcNow);
        while (true)
        {
            if (ct.IsCancellationRequested)
            {
                await eventHubReceiver.CloseAsync();
                break;
            }

            EventData eventData = await eventHubReceiver.ReceiveAsync(new TimeSpan(0,0,10));

            if (eventData != null)
            {
                string data = Encoding.UTF8.GetString(eventData.GetBytes());
                Console.WriteLine("Message received. Partition: {0} Data: '{1}'", partition, data);
            }
        }
    }
}

Passaggi successiviNext steps

Per altre informazioni sulle funzionalità dell'hub IoT, vedere:To further explore the capabilities of IoT Hub, see: