Seguimiento de mensajes del dispositivo a la nube de Azure IoT mediante el seguimiento distribuido (versión preliminar)

Artículo
03/09/2024

Use el seguimiento distribuido (versión preliminar) en IoT Hub para supervisar los mensajes de IoT a medida que pasan a través de los servicios de Azure. IoT Hub es uno de los primeros servicios de Azure que admite el seguimiento distribuido. A medida que más servicios de Azure admitan el seguimiento distribuido, podrá rastrear los mensajes de Internet de las cosas (IoT) a través de los servicios de Azure involucrados en su solución. Para obtener más información sobre esta característica, consulte ¿Qué es el seguimiento distribuido?

Al habilitar el seguimiento distribuido en IoT Hub, puede hacer lo siguiente:

Supervisar de forma precisa el flujo de cada mensaje a través de IoT Hub mediante el contexto de seguimiento. El contexto de seguimiento incluye identificadores de correlación que permiten correlacionar eventos de un componente con eventos de otro componente. Un dispositivo gemelo permite aplicarlo a un subconjunto o a todos los mensajes de dispositivo IoT.
Registre el contexto de seguimiento en Registros de Azure Monitor.
Medir y comprender la latencia y el flujo de mensajes desde los dispositivos a IoT Hub y los puntos de conexión de enrutamiento.

Importante

El seguimiento distribuido de una instancia de Azure IoT Hub está actualmente en versión preliminar. Consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure para conocer los términos legales que se aplican a las características de Azure que se encuentran en la versión beta, en versión preliminar o que todavía no se han publicado para que estén disponibles con carácter general.

Requisitos previos

Una instancia de Azure IoT Hub creada en una de las siguientes regiones.
- Norte de Europa
- Sudeste de Asia
- Oeste de EE. UU. 2
Un dispositivo registrado en el centro de IoT. Si no tiene uno, siga los pasos descritos en Registro de un nuevo dispositivo en el centro de IoT y guarde la cadena de conexión del dispositivo para usarla en este artículo.
En este artículo se da por supuesto que está familiarizado con el envío de mensajes de telemetría a IoT hub.
La última versión de Git.

Consideraciones y límites de la versión preliminar pública

Tenga en cuenta las siguientes limitaciones para determinar si esta característica en vista previa (GB) es adecuada para sus escenarios:

La propuesta del estándar W3C Trace Context es actualmente un borrador de trabajo.
El único lenguaje de desarrollo que admite actualmente el SDK de cliente es C, en la rama versión preliminar pública del SDK de dispositivo IoT de Azure para C
La funcionalidad de la nube al dispositivo gemelo no está disponible para el nivel básico de IoT Hub. Sin embargo, IoT Hub seguirá registrando en Azure Monitor si ve un encabezado de contexto de seguimiento compuesto correctamente.
Para garantizar un funcionamiento eficaz, IoT Hub impondrá una limitación en la tasa de registro que se puede producir como parte del seguimiento distribuido.
La característica de seguimiento distribuido solo se admite para centros de IoT creados en las siguientes regiones:
- Norte de Europa
- Sudeste de Asia
- Oeste de EE. UU. 2

Descripción del seguimiento distribuido de Azure IoT

Muchas soluciones de IoT, incluida la arquitectura de referencia de Azure IoT, suelen seguir una variante de la arquitectura de microservicios. A medida que una solución de IoT se vuelve más compleja, se termina usando una docena o más de microservicios. Estos microservicios pueden provenir, o no, de Azure.

La identificación de dónde se quitan o ralentizan los mensajes puede ser un reto. Por ejemplo, imagine que tiene una solución de IoT que usa cinco servicios diferentes de Azure y 1500 dispositivos activos. Cada dispositivo envía 10 mensajes del dispositivo a la nube por segundo, lo que hace un total de 15 000 mensajes por segundo. Pero observa que la aplicación web solo ve 10 000 mensajes por segundo. ¿Cómo encontrar la causa?

Para reconstruir el flujo de un mensaje de IoT en los servicios, cada servicio debe propagar un identificador de correlación que identifica inequívocamente el mensaje. Después de que Azure Monitor recopile los identificadores de correlación en un sistema centralizado, se pueden usar para ver el flujo de mensajes. Este método se denomina patrón de seguimiento distribuido.

Para admitir una adopción más amplia para el seguimiento distribuido, Microsoft está contribuyendo a la propuesta estándar de W3C para el seguimiento distribuido. Cuando se habilite la compatibilidad con el seguimiento distribuido para IoT Hub, se seguirá este flujo para cada mensaje generado:

Se genera un mensaje en el dispositivo de IoT.
El dispositivo IoT decide (con la ayuda de la nube) que este mensaje se debería asignar con un contexto de seguimiento.
El SDK agrega un valor tracestate a la propiedad del mensaje, que contiene la marca de tiempo para la creación de mensajes.
El dispositivo de IoT envía el mensaje a IoT Hub.
El mensaje llega a la puerta de enlace de IoT Hub.
IoT Hub busca el valor tracestate en las propiedades del mensaje y comprueba si tiene el formato correcto. En caso afirmativo, IoT Hub genera un valor trace-id único global para el mensaje y un valor span-id para el "salto". IoT Hub registra estos valores en los registros de seguimiento distribuidos de IoT Hub en la operación DiagnosticIoTHubD2C.
Cuando el procesamiento del mensaje finaliza, IoT Hub genera otro valor span-id y lo registra, junto con el valor trace-id existente, en la operación DiagnosticIoTHubIngress.
Si el enrutamiento está habilitado para el mensaje, IoT Hub lo escribe en el punto de conexión personalizado. IoT Hub registra otro valor span-id con el mismo valor trace-id en la categoría DiagnosticIoTHubEgress.

Configuración del seguimiento distribuido en un centro de IoT

En esta sección, va a configurar un centro de IoT para registrar atributos de seguimiento distribuido (identificadores de correlación y marcas de tiempo).

En Azure Portal, vaya a su centro de IoT.
En el panel izquierdo del centro, desplácese hacia abajo hasta la sección Supervisión y seleccione Configuración de diagnóstico.
Seleccione Agregar configuración de diagnóstico.
En el cuadro Nombre de configuración de diagnóstico, escriba el nombre de la nueva configuración de diagnóstico. Por ejemplo, escriba DistributedTracingSettings.
Elija una o varias de las siguientes opciones de Detalles del destino para determinar dónde enviar la información de registro:
- Archivar en una cuenta de almacenamiento: configure una cuenta de almacenamiento para que contenga la información de registro.
- Transmisión a un centro de eventos: configure un centro de eventos para que contenga la información de registro.
- Enviar a Log Analytics: configure un área de trabajo de Log Analytics para que contenga la información de registro.
En la sección Registros, seleccione las operaciones que desea registrar.

Incluya Seguimiento distribuido y configure un periodo en Retención para establecer el número de días que desea conservar el registro. La retención de registros afecta a los costos de almacenamiento.
Seleccione Guardar.
(Opcional) Para ver el flujo de los mensajes a distintos lugares, configure reglas de enrutamiento para al menos dos puntos de conexión diferentes.

Tras la activación del registro, IoT Hub graba un registro cuando un mensaje que contiene las propiedades de seguimiento válidas se encuentra en cualquiera de las siguientes situaciones:

El mensaje llega a la puerta de enlace del centro de IoT.
El centro de IoT procesa el mensaje.
El mensaje se enruta a puntos de conexión personalizados. El enrutamiento debe estar habilitado.

Para obtener más información sobre estos registros y sus esquemas, consulte Supervisión de IoT Hub y Seguimiento distribuido en registros de recursos de IoT Hub.

Actualización de opciones de ejemplo

Para cambiar el porcentaje de mensajes que se van a seguir desde la nube, debe actualizar el dispositivo gemelo. Puede realizar actualizaciones mediante el editor JSON en Azure Portal o el SDK del servicio IoT Hub. En las subsecciones siguientes se proporcionan ejemplos.

Actualización de un único dispositivo

Puede usar Azure Portal o la extensión de Azure IoT Hub para Visual Studio Code (VS Code) para actualizar la frecuencia de muestreo de un único dispositivo.

Azure Portal
Código de VS

Vaya al centro de IoT en Azure Portal y seleccione Dispositivos en la sección Administración de dispositivos del menú.
Elija un dispositivo.
Seleccione el icono de engranaje en Seguimiento distribuido (versión preliminar). En el panel que se abre:
1. Seleccione la opción Habilitar.
2. En Frecuencia de muestreo, elija un porcentaje entre 0 y 100.
3. Seleccione Guardar.
Espere unos segundos y seleccione Actualizar. Si el dispositivo confirma correctamente los cambios, aparecerá un icono de sincronización con una marca de verificación.

Actualización en bloque de varios dispositivos

Para actualizar la configuración de muestreo del seguimiento distribuido para varios dispositivos, use la configuración automática de dispositivos. Siga este esquema gemelo:

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

Nombre del elemento	Obligatorio	Type	Descripción
`sampling_mode`	Sí	Entero	Actualmente se admiten dos valores de modo para activar o desactivar el muestreo. `1` significa activado y `2` desactivado.
`sampling_rate`	Sí	Entero	Este valor es un porcentaje. Solo se permiten valores de `0` a `100` (inclusive).

Consulta y visualización de seguimientos

Para ver todos los seguimientos registrados por una instancia de IoT Hub, consulte el almacén de registro que seleccionó en la configuración de diagnóstico. En esta sección se muestra cómo realizar consultas mediante Log Analytics.

Si configura Log Analytics con registros de recursos, consulte los registros en la categoría DistributedTracing. Por ejemplo, esta consulta muestra todos los seguimientos registrados:

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

Estos son algunos registros de ejemplo en Log Analytics:

Hora de generación	Nombre de la operación	Category	Nivel	Id. de correlación	Duración, en milisegundos	Propiedades
2018-02-22T03:28:28.633Z	DiagnosticIoTHubD2C	DistributedTracing	Informativo	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	Informativo	00-8cd869a412459a25f5b4f31311223344-349810a9bbd28730-01	20	`{"isRoutingEnabled":"false","parentSpanId":"0144d2590aacd909"}`
2018-02-22T03:28:48.633Z	DiagnosticIoTHubEgress	DistributedTracing	Informativo	00-8cd869a412459a25f5b4f31311223344-349810a9bbd28730-01	23	`{"endpointType":"EventHub","endpointName":"myEventHub", "parentSpanId":"0144d2590aacd909"}`

Para conocer los tipos de registros, consulte Registros de seguimiento distribuido de Azure IoT Hub.

Ejecución de una aplicación de ejemplo

En esta sección, preparará un entorno de desarrollo para usarse con el SDK de Azure IoT para C. Luego, modificará uno de los ejemplos para habilitar el seguimiento distribuido en los mensajes de telemetría del dispositivo.

Estas instrucciones sirven para generar el muestreo en Windows. Para otros entornos, consulte Compile the C SDK (Compilar el SDK de C) o Prepackaged C SDK for Platform Specific Development (SDK de C previamente empaquetado para el desarrollo específico de plataforma).

Clonación del código fuente e inicialización

Instale la carga de trabajo Desarrollo para el escritorio con C++ para Visual Studio 2022. También se admite Visual Studio 2019.
Instale CMake. Asegúrese de que se encuentra en PATH, para lo que debe especificar cmake -version desde un símbolo del sistema.
Abra un símbolo del sistema o el shell de Bash de Git. Ejecute los siguientes comandos para clonar la versión más reciente de la rama de versión preliminar pública del SDK de Azure IoT C del repositorio de GitHub:
```
git clone -b public-preview https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c
git submodule update --init
```
Esta operación puede tardar varios minutos en finalizar.
Ejecute los siguientes comandos desde el directorio azure-iot-sdk-c para crear un subdirectorio cmake y vaya a la carpeta cmake:
```
mkdir cmake
cd cmake
cmake ..
```
Si CMake no encuentra el compilador de C++, es posible que encuentre errores de compilación al ejecutar el comando anterior. Si eso sucede, pruebe a ejecutar este comando en el símbolo del sistema de Visual Studio.

Tras realizar la compilación, las últimas líneas de salida tendrán un aspecto similar al siguiente:
```
$ 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
```

Edición del ejemplo de telemetría de para habilitar el seguimiento distribuido

En esta sección, editará el ejemplo de iothub_ll_telemetry_sample.c en el repositorio del SDK para habilitar el seguimiento distribuido. O bien, puede copiar una versión ya editada del ejemplo desde el repositorio de azure-iot-distributed-tracing-sample.

Utilice un editor para abrir el archivo de origen azure-iot-sdk-c/iothub_client/samples/iothub_ll_telemetry_sample/iothub_ll_telemetry_sample.c.

Busque la declaración de la constante 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;

Reemplace el valor de la constante connectionString por la cadena de conexión del dispositivo que guardó en la sección Registrar un dispositivo del inicio rápido para enviar la telemetría.

Busque la línea de código que llama a IoTHubDeviceClient_LL_SetConnectionStatusCallback para registrar una función de devolución de llamada de estado de conexión antes del bucle de mensajes de envío. Agregue el código en esa línea para llamar a IoTHubDeviceClient_LL_EnablePolicyConfiguration habilitando el seguimiento distribuido para el 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 función IoTHubDeviceClient_LL_EnablePolicyConfiguration habilita directivas para características específicas de IoT Hub que se configuran a través dispositivos gemelos. Tras habilitar POLICY_CONFIGURATION_DISTRIBUTED_TRACING mediante la línea de código adicional, el comportamiento del seguimiento del dispositivo reflejará los cambios de seguimiento distribuido realizados en el dispositivo gemelo.

Para que la aplicación de ejemplo siga ejecutándose sin usar toda la cuota, agregue un retraso de un segundo al final del bucle de mensaje de envío:

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

Compilación y ejecución

Vaya al directorio del proyecto iothub_ll_telemetry_sample desde el directorio de CMake (azure-iot-sdk-c/cmake) que creó anteriormente y compile el ejemplo:
```
cd iothub_client/samples/iothub_ll_telemetry_sample
cmake --build . --target iothub_ll_telemetry_sample --config Debug
```
Ejecute la aplicación. El dispositivo envía datos de telemetría compatibles con el seguimiento distribuido.
```
Debug/iothub_ll_telemetry_sample.exe
```
Mantenga la aplicación en ejecución. Puede observar los mensajes que se envían a IoT Hub en la ventana de la consola.

Para una aplicación cliente que pueda recibir decisiones de muestreo de la nube, pruebe el ejemplo iothub_devicetwin_sample.c en el repositorio de ejemplo de seguimiento distribuido.

Solución alternativa para clientes que no son de Microsoft

La implementación de la característica de seguimiento distribuido sin usar el SDK de C es más compleja. Esta opción no se recomienda.

En primer lugar, debe implementar todos los primitivos del protocolo de IoT Hub en los mensajes; para ello, siga la guía de desarrollo Creación y lectura de mensajes de IoT Hub. Luego, edite las propiedades del protocolo en los mensajes de MQTT y AMQP para agregar tracestate como propiedad del sistema.

Concretamente:

En el caso de MQTT, agregue %24.tracestate=timestamp%3d1539243209 al tema del mensaje. Reemplace 1539243209 por la hora de creación del mensaje en formato de marca de tiempo de Unix. A modo de ejemplo, consulte la implementación en el SDK de C.
En AMQP, agregar key("tracestate") y value("timestamp=1539243209") como anotación del mensaje. Para obtener una implementación de referencia, consulte el archivo uamqp_messaging.c.

Para controlar el porcentaje de mensajes que contienen esta propiedad, implemente la lógica para que escuche eventos iniciados en la nube, como las actualizaciones gemelas.

Pasos siguientes

Para obtener más información sobre el patrón general del seguimiento distribuido en microservicios, consulte Microservice architecture pattern: distributed tracing (Patrón de arquitectura de microservicios: seguimiento distribuido).

Compartir vía