Rastrear mensagens de dispositivo para a nuvem de Internet das Coisas do Azure usando o rastreamento distribuído (versão prévia)

Use o rastreamento distribuído (versão prévia) no Hub IoT para monitorar mensagens de IoT à medida que elas passam pelos serviços do Azure. O Hub IoT é um dos primeiros serviços do Azure a dar suporte ao rastreamento distribuído. À medida que mais serviços do Azure suportam rastreamento distribuído, você pode rastrear mensagens de Internet das Coisas (IoT) em todos os serviços do Azure envolvidos na sua solução. Para obter mais informações sobre o recurso, consulte O que é rastreamento distribuído?.

Ao habilitar o rastreamento distribuído para o Hub IoT, você pode:

• Monitorar o fluxo de cada mensagem por meio do Hub IoT usando o contexto de rastreamento. O contexto de rastreamento inclui as IDs de correlação que permitem correlacionar eventos de um componente com eventos de outro componente. Você pode aplicá-lo a um subconjunto ou a todas as mensagens de dispositivo IoT usando um dispositivo gêmeo.
• Registre o contexto do rastreamento nos Logs do Azure Monitor.
• Meça e compreenda o fluxo de mensagens e a latência dos dispositivos para o Hub IoT e os pontos de extremidade de roteamento.

Importante

O rastreamento distribuído de um Hub IoT do Azure está atualmente em VERSÃO PRÉVIA. Veja os Termos de Uso Complementares para Versões Prévias do Microsoft Azure para obter termos legais que se aplicam aos recursos do Azure que estão em versão beta, versão prévia ou que, de outra forma, ainda não foram lançados em disponibilidade geral.

Pré-requisitos

• Um hub IoT do Azure criado em uma das regiões a seguir.

  • Norte da Europa
  • Sudeste Asiático
  • Oeste dos EUA 2

• Um dispositivo registrado em seu hub IoT. Se você não tiver um, siga as etapas em Registrar um novo dispositivo no hub IoT e salve a cadeia de conexão do dispositivo a ser usada neste artigo.

• Este artigo pressupõe que você esteja familiarizado com o envio de mensagens de telemetria ao Hub IoT.

• A versão mais recente do Git.

Considerações e limites sobre a visualização pública

Considere as seguintes limitações para determinar se essa versão prévia do recurso é adequada para seus cenários:

• A proposta atual do padrão do Contexto de Rastreamento do W3C é um rascunho de trabalho.

• A única linguagem de desenvolvimento compatível com o SDK do cliente atualmente é a C, no branch de visualização pública do SDK do dispositivo IoT do Azure para C

• O recurso de dispositivo gêmeo de nuvem para dispositivo não está disponível para a camada básica do Hub IoT. No entanto, o Hub IoT ainda registra no Azure Monitor se ele vê um cabeçalho de contexto de rastreamento composto corretamente.

• Para garantir uma operação eficiente, o Hub IoT impõe uma aceleração na taxa de registro que pode ocorrer como parte do rastreamento distribuído.

• O recurso de rastreamento distribuído tem suporte apenas para hubs IoT criados nas seguintes regiões:

  • Norte da Europa
  • Sudeste Asiático
  • Oeste dos EUA 2

Entenda o rastreamento distribuído do Azure IoT

Muitas soluções de IoT, incluindo a arquitetura de referência de Internet das Coisas do Azure, geralmente seguem uma variante da arquitetura de microsserviços. À medida que uma solução de IoT se torna mais complexa, você acaba por usar 12 ou mais microsserviços. Esses microsserviços podem ou não ser do Azure.

Identifique onde as mensagens de IoT são soltas ou a diminuição da velocidade poderá se tornar um desafio. Por exemplo, imagine que você tenha uma solução de IoT que usa cinco serviços diferentes do Azure e 1.500 dispositivos ativos. Cada dispositivo envia 10 mensagens de dispositivo para nuvem por segundo, totalizando 15.000 mensagens por segundo. Mas você percebe que o aplicativo Web vê apenas 10.000 mensagens por segundo. Consegue encontrar o culpado?

Para você reconstruir o fluxo de uma mensagens de IoT em diferentes serviços, cada serviço deverá propagar uma ID de correlação que identifica exclusivamente a mensagem. Depois que o Azure Monitor coletar IDs de correlação em um sistema centralizado, você poderá usar essas IDs para ver o fluxo de mensagens. Esse método é chamado de padrão de rastreamento distribuído.

Para prestar suporte a uma adoção mais ampla do rastreamento distribuído, a Microsoft contribuirá para a proposta padrão do W3C para o rastreamento distribuído. Quando o suporte a rastreamento distribuído para o Hub IoT está habilitado, ele segue esse fluxo para cada mensagem gerada:

1. Uma mensagem é gerada no dispositivo IoT.
2. O dispositivo IoT decide (com a ajuda da nuvem) se essa mensagem deve ser atribuída com um contexto de rastreamento.
3. O SDK adiciona um valor tracestate à propriedade da mensagem, que contém o carimbo de data/hora da criação da mensagem.
4. O dispositivo IoT envia a mensagem ao Hub IoT.
5. A mensagem chega no gateway do Hub IoT.
6. O Hub IoT procura o valor de tracestate nas propriedades da mensagem e verifica se ele tem o formato correto. Nesse caso, o Hub IoT gera um valor de trace-id globalmente exclusivo para a mensagem e um valor span-id para o "salto". O Hub IoT registra esses valores nos Logs de rastreamento distribuídos do Hub IoT na operação DiagnosticIoTHubD2C.
7. Quando o processamento da mensagem é concluído, o Hub IoT gera outro valor de span-id e o registra com o valor trace-id existente, na operação DiagnosticIoTHubIngress.
8. Se o roteamento estiver habilitado para a mensagem, o Hub IoT o registrará no ponto de extremidade personalizado. O Hub IoT registra outro valor span-id com o mesmo valor trace-id na categoria DiagnosticIoTHubEgress.

Configurar o rastreamento distribuído em um hub IoT

Nesta seção, você configura um Hub IoT para registrar atributos de rastreamento distribuído (IDs de correlação e carimbos de data/hora).

1. Vá até o hub IoT no portal do Azure.

2. No painel esquerdo do hub IoT, role para baixo até a seção Monitoramento e selecione Configurações de diagnóstico.

3. Selecione Adicionar configuração de diagnóstico.

4. Na caixa Nome da configuração de diagnóstico, insira um nome para uma nova configuração de diagnóstico. Por exemplo, insira DistributedTracingSettings.

   

5. Escolha uma ou mais das seguintes opções em Detalhes do destino para determinar para onde enviar as informações de registro:

   • Arquivar em uma conta de armazenamento: configure uma conta de armazenamento para conter as informações de registro em log.
   • Transmitir para um hub de eventos: configure um hub de eventos para conter as informações de registro em log.
   • Enviar para o Log Analytics: configure um workspace do Log Analytics para conter as informações de registro em log.

6. Na seção Logs, selecione as operações que deseja registrar.

   Inclua Rastreamento Distribuído e configure um período de Retenção com a quantidade de dias que deseja que o registro em log seja retido. A retenção de logs afeta os custos de armazenamento.

   

7. Selecione Salvar.

8. (Opcional) Para ver as mensagens fluírem para locais diferentes, configure regras de roteamento para, no mínimo, dois pontos de extremidade diferentes.

Depois que o registro em log for ativado, o Hub IoT registrará um log quando uma mensagem contendo propriedades de rastreamento válidas for encontrada em qualquer uma das seguintes situações:

• A mensagem chega no gateway do hub IoT.
• O hub IoT processa a mensagem.
• A mensagem é roteada aos pontos de extremidade personalizados. O roteamento deve ser ativado.

Para saber mais sobre esses logs e seus esquemas, confira Monitorar o Hub IoT e Rastreamento distribuído em logs de recursos do Hub IoT.

Atualizar opções de amostragem

Para alterar a porcentagem de mensagens que serão rastreadas na nuvem, você deve atualizar o dispositivo gêmeo. Você pode fazer atualizações usando o editor de JSON no portal do Azure ou no SDK do serviço de Hub IoT. As subseções a seguir fornecem exemplos.

Atualizar um único dispositivo

Você pode usar o portal do Azure ou a extensão do Hub IoT do Azure para Visual Studio Code (VS Code) para atualizar a taxa de amostragem de um único dispositivo.

Portal do Azure

1. Vá para o hub IoT no portal do Azure e selecione Dispositivos na seção Gerenciamento de dispositivos do menu.

2. Escolha seu dispositivo.

3. Selecione o ícone de engrenagem em Rastreamento Distribuído (versão prévia). No painel que é aberto:

   1. Selecione a opção Habilitar.
   2. Para Taxa de amostragem, escolha uma porcentagem entre 0 e 100.
   3. Clique em Salvar.

   

4. Aguarde alguns segundos e selecione Atualizar. Se o dispositivo reconhecer com êxito suas alterações, um ícone de sincronização com uma marca de seleção será exibido.

Código do VS

1. Com o Visual Studio Code instalado, instale a versão mais recente da extensão do Hub IoT do Azure para o Visual Studio Code.

2. Abra o Visual Studio Code e acesse a guia Explorer e a seção Hub IoT do Azure.

3. Selecione as reticências (...) ao lado de Hub IoT do Azure para ver um submenu. Escolha a opção Selecionar Hub IoT para recuperar o hub IoT do Azure.

   Na janela pop-up exibida na parte superior do Visual Studio Code, você pode selecionar sua assinatura e o Hub IoT.

   Veja uma demonstração na página do GitHub vscode-azure-iot-toolkit.

4. Expanda o dispositivo em Dispositivos. Clique com o botão direito do mouse em Configuração de Rastreamento Distribuído (Versão Prévia) e selecione Atualizar Configuração de Rastreamento Distribuído (Versão Prévia).

5. No painel pop-up que aparece na parte superior da janela, selecione Habilitar.

   

   Habilitar Rastreamento Distribuído: habilitado agora aparece em Configuração de Rastreamento Distribuído (Versão Prévia)>Desejado.

6. No painel pop-up exibido para a taxa de amostragem, insira um número inteiro entre 0 e 100 e selecione a tecla Enter.

   

   Taxa de amostra: 100(%) agora aparece em Configuração de Rastreamento Distribuído (Versão Prévia)>Desejado.

Atualizar em massa vários dispositivos

Para atualizar a configuração da amostragem do rastreamento distribuído para vários dispositivos, use a configuração automática de dispositivos. Siga este esquema gêmeo:

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

Nome do elemento	Obrigatório	Type	Descrição
sampling_mode	Sim	Integer	Atualmente, há suporte para dois valores de modo para ativar e desativar a amostragem. 1 está ativado e 2 está desativado.
sampling_rate	Sim	Integer	Esse valor é uma porcentagem. Somente valores de 0 para 100 (inclusive) são permitidos.

Consultar e visualizar rastreamentos

Para ver todos os rastreamentos registrados por um hub IoT, consulte o armazenamento de log escolhido nas configurações de diagnóstico. Esta seção mostra como consultar usando o Log Analytics.

Se você configurou o Log Analytics com logs de recurso, consulte procurando logs na categoria DistributedTracing. Por exemplo, esta consulta mostra todos os rastreamentos registrados:

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

Aqui estão alguns logs de exemplo no Log Analytics:

Hora da geração	Nome da operação	Categoria	Nível	ID de Correlação	Duração em milissegundos	Propriedades
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 entender os tipos de logs, confira Logs de rastreamento distribuído do Hub IoT do Azure.

Executar um aplicativo de exemplo

Nesta seção, você preparará um ambiente de desenvolvimento para ser usado com o SDK de C do IoT do Azure. Em seguida, você modificará um dos exemplos para habilitar o rastreamento distribuído em mensagens de telemetria de seu dispositivo.

Essas instruções servem para compilar o exemplo no Windows. Para outros ambientes, confira Compilar o SDK de C ou SDK de C predefinido para o Desenvolvimento específico de plataforma.

Clonar o código-fonte e inicializar

1. Instale a carga de trabalho Desenvolvimento de área de trabalho com C++ para o Visual Studio 2022. O Visual Studio 2019 também tem suporte.

2. Instale o CMake. Verifique se ele está em seu PATH inserindo cmake -version por meio de um prompt de comando.

3. Abra um prompt de comando ou o shell Bash do Git. Execute os seguintes comandos para clonar a última versão do branch de visualização pública do repositório do GitHub do SDK de C do 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
   

   Essa operação deve demorar alguns minutos para ser concluída.

4. Execute os seguintes comandos no diretório azure-iot-sdk-c para criar um subdiretório cmake e vá para a pasta cmake:

   mkdir cmake
   cd cmake
   cmake ..
   

   Se o CMake não conseguir encontrar seu compilador C++, você poderá encontrar erros de compilação ao executar o comando anterior. Se isso acontecer, tente executar o comando no prompt de comando do Visual Studio.

   Após o sucesso do build, as últimas linhas de saída serão semelhantes à seguinte saída:

   $ 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
   

Editar o exemplo de telemetria para habilitar o rastreamento distribuído

Nesta seção, você editará o exemplo iothub_ll_telemetry_sample.c no repositório do SDK para habilitar o rastreamento distribuído. Ou você pode copiar uma versão já editada do exemplo do repositório azure-iot-distributed-tracing-sample.

1. Use um editor para abrir o arquivo de origem azure-iot-sdk-c/iothub_client/samples/iothub_ll_telemetry_sample/iothub_ll_telemetry_sample.c.

2. Localize a declaração da 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;
   

   Substitua o valor da constante connectionString pela cadeia de conexão do dispositivo que você salvou na seção Registrar um dispositivo do início rápido para enviar telemetria.

3. Encontre a linha de código que chama IoTHubDeviceClient_LL_SetConnectionStatusCallback para registrar uma função de retorno de chamada do status da conexão antes do loop de envio de mensagens. Adicione o código sob essa linha para chamar IoTHubDeviceClient_LL_EnablePolicyConfiguration e habilitar o rastreamento distribuído para o 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)
   

   A função IoTHubDeviceClient_LL_EnablePolicyConfiguration habilita políticas para recursos específicos do Hub IoT que são configurados por meio de dispositivos gêmeos. Após você habilitar POLICY_CONFIGURATION_DISTRIBUTED_TRACING usando a linha de código extra, o comportamento de rastreamento do dispositivo refletirá as alterações do rastreamento distribuído realizadas no dispositivo gêmeo.

4. Para manter o aplicativo de exemplo em execução sem o usar toda a sua cota, adicione um segundo de atraso no final do loop de envio de mensagens:

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

Compilar e executar

1. Vá até o diretório de projeto iothub_ll_telemetry_sample no diretório do CMake (azure-iot-sdk-c/cmake) criado anteriormente e compile o exemplo:

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

2. Execute o aplicativo. O dispositivo envia telemetria que dá suporte ao rastreamento distribuído.

   Debug/iothub_ll_telemetry_sample.exe
   

3. Mantenha o aplicativo em execução. Você pode observar as mensagens que estão sendo enviadas para o Hub IoT na janela do console.

Para um aplicativo cliente que pode receber decisões de amostragem da nuvem, experimente o exemplo iothub_devicetwin_sample.c no repositório de exemplo de rastreamento distribuído.

Solução alternativa para clientes que não são da Microsoft

Implementar o recurso de rastreamento distribuído sem usar o SDK do C é mais complexo. Não recomendamos isso.

Primeiro, você precisa implementar todos os primitivos de protocolo do Hub IoT em suas mensagens seguindo o guia de desenvolvedor Criar e ler mensagens do Hub IoT. Depois, edite as propriedades de protocolo nas mensagens de MQTT e AMQP para adicionar tracestate como uma propriedade do sistema.

Especificamente:

• Para MQTT, adicione %24.tracestate=timestamp%3d1539243209 ao tópico da mensagem. Substitua 1539243209 pela hora de criação da mensagem no formato de carimbo de data/hora Unix. Para ver um exemplo, confira a implementação no SDK de C.
• Para o AMQP, adicione key("tracestate") e value("timestamp=1539243209") como anotação de mensagem. Para obter uma implementação de referência, consulte o arquivo uamqp_messaging.c.

Para controlar a porcentagem de mensagens que contêm essa propriedade, implemente a lógica para ouvir eventos iniciados na nuvem, como atualizações gêmeas.

Próximas etapas

• Para saber mais sobre o padrão geral do rastreamento distribuído em microsserviços, confira Padrão de arquitetura do microsserviço: rastreamento distribuído.