Rastrear mensagens de dispositivo para nuvem do Azure IoT usando rastreamento distribuído (visualização)

Artigo
03/05/2024

Use o rastreamento distribuído (visualização) no Hub IoT para monitorar mensagens de IoT à medida que passam pelos serviços do Azure. O Hub IoT é um dos primeiros serviços do Azure a oferecer suporte ao rastreamento distribuído. À medida que mais serviços do Azure oferecem suporte ao rastreamento distribuído, você pode rastrear mensagens da Internet das Coisas (IoT) em todos os serviços do Azure envolvidos em 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:

Monitore o fluxo de cada mensagem por meio do Hub IoT usando o contexto de rastreamento. O contexto de rastreamento inclui 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 dispositivos IoT usando um gêmeo de dispositivo.
Registre o contexto de rastreamento nos Logs do Azure Monitor.
Meça e compreenda o fluxo e a latência de mensagens de dispositivos para o Hub IoT e pontos de extremidade de roteamento.

Importante

O rastreamento distribuído de um Hub IoT do Azure está atualmente em visualização. Veja Termos de Utilização Complementares da Pré-visualizações do Microsoft Azure para obter os termos legais que se aplicam às funcionalidades do Azure que estão na versão beta, na pré-visualização ou que ainda não foram lançadas para disponibilidade geral.

Pré-requisitos

Um hub IoT do Azure criado em uma das seguintes regiões.
- Europa do Norte
- Sudeste Asiático
- E.U.A. Oeste 2
Um dispositivo registrado em seu hub IoT. Se você não tiver um dispositivo em seu hub IoT, siga as etapas em Registrar um dispositivo e salve a cadeia de conexão do dispositivo para usar neste artigo.
Este artigo pressupõe que você esteja familiarizado com o envio de mensagens de telemetria para seu hub IoT.
A última versão do Git.

Limites e considerações da visualização pública

Considere as seguintes limitações para determinar se esse recurso de visualização é adequado para seus cenários:

A proposta para o padrão W3C Trace Context é atualmente um rascunho de trabalho.
A única linguagem de desenvolvimento que o SDK do cliente suporta atualmente é C, na ramificação de visualização pública do SDK do dispositivo IoT do Azure para C
O recurso de 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 vir um cabeçalho de contexto de rastreamento composto corretamente.
Para garantir uma operação eficiente, o Hub IoT impõe uma limitação na taxa de registro em log que pode ocorrer como parte do rastreamento distribuído.
O recurso de rastreamento distribuído é suportado apenas para hubs IoT criados nas seguintes regiões:
- Europa do Norte
- Sudeste Asiático
- E.U.A. Oeste 2

Compreender o rastreamento distribuído do Azure IoT

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

Identificar onde as mensagens de IoT estão caindo ou diminuindo a velocidade pode ser um desafio. Por exemplo, imagine que você tem uma solução de IoT que usa cinco serviços diferentes do Azure e 1.500 dispositivos ativos. Cada dispositivo envia 10 mensagens do dispositivo para a nuvem por segundo, para um total de 15.000 mensagens por segundo. Mas você percebe que seu aplicativo Web vê apenas 10.000 mensagens por segundo. Como encontrar o culpado?

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

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

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

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

Vá para seu hub IoT no portal do Azure.
No painel esquerdo do seu hub IoT, role para baixo até a seção Monitoramento e selecione Configurações de diagnóstico.
Selecione Adicionar definição de diagnóstico.
Na caixa Nome da configuração de diagnóstico, insira um nome para uma nova configuração de diagnóstico. Por exemplo, insira DistributedTracingSettings.
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.
- Transmitir para um hub de eventos: configure um hub de eventos para conter as informações de log.
- Enviar para o Log Analytics: configure um espaço de trabalho do Log Analytics para conter as informações de registro.
Na seção Logs, selecione as operações que deseja registrar.

Inclua o Rastreamento Distribuído e configure um período de Retenção para quantos dias você deseja que o log seja mantido. A retenção de logs afeta os custos de armazenamento.
Selecione Guardar.
(Opcional) Para ver o fluxo de mensagens para locais diferentes, configure regras de roteamento para pelo menos dois pontos de extremidade diferentes.

Depois que o log é ativado, o Hub IoT registra um log quando uma mensagem que contém propriedades de rastreamento válidas é encontrada em qualquer uma das seguintes situações:

A mensagem chega ao gateway do hub IoT.
O hub IoT processa a mensagem.
A mensagem é roteada para pontos de extremidade personalizados. O roteamento deve estar habilitado.

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

Atualizar opções de amostragem

Para alterar a percentagem de mensagens a rastrear a partir da nuvem, tem de atualizar o gémeo do dispositivo. Você pode fazer atualizações usando o editor JSON no portal do Azure ou o SDK do serviço Hub IoT. As subsecções seguintes 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
Código VS

Vá para seu hub IoT no portal do Azure e selecione Dispositivos na seção Gerenciamento de dispositivos do menu.
Escolha o seu dispositivo.
Selecione o ícone de engrenagem em Rastreamento distribuído (visualização). No painel que se abre:
1. Selecione a opção Ativar .
2. Para Taxa de amostragem, escolha uma percentagem entre 0 e 100.
3. Selecione Guardar.
Aguarde alguns segundos e selecione Atualizar. Se o dispositivo reconhecer com êxito as alterações, será apresentado um ícone de sincronização com uma marca de verificação.

Atualização em massa de vários dispositivos

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

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

Nome do elemento	Necessário	Type	Description
`sampling_mode`	Sim	Número inteiro	Atualmente, há suporte para dois valores de modo para ativar e desativar a amostragem. `1` está ligado, e `2` está desligado.
`sampling_rate`	Sim	Número inteiro	Este valor é uma percentagem. Apenas valores de `0` até `100` (inclusive) são permitidos.

Consultar e visualizar rastreamentos

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

Se você configurar o DistributedTracing Log Analytics com logs de recursos, consulte procurando logs na categoria. 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 exemplos de logs no Log Analytics:

Hora de geração	Nome da operação	Categoria	Level	ID de Correlação	Duração em milissegundos	Propriedades
2018-02-22T03:28:28.633Z	DiagnósticoIoTHubD2C	Rastreio Distribuído	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	DiagnósticoIoTHubIngress	Rastreio Distribuído	Informativo	00-8CD869A412459A25F5B4F31311223344-349810A9BBD28730-01	20	`{"isRoutingEnabled":"false","parentSpanId":"0144d2590aacd909"}`
2018-02-22T03:28:48.633Z	DiagnosticIoTHubEgress	Rastreio Distribuído	Informativo	00-8CD869A412459A25F5B4F31311223344-349810A9BBD28730-01	23	`{"endpointType":"EventHub","endpointName":"myEventHub", "parentSpanId":"0144d2590aacd909"}`

Para entender os tipos de logs, consulte Logs de rastreamento distribuído do Hub IoT do Azure.

Executar um aplicativo de exemplo

Nesta seção, você prepara um ambiente de desenvolvimento para uso com o SDK do Azure IoT C. Em seguida, modifique um dos exemplos para habilitar o rastreamento distribuído nas mensagens de telemetria do dispositivo.

Estas instruções são para criar o exemplo no Windows. Para outros ambientes, consulte Compilar o C SDK ou o C SDK pré-empacotado para desenvolvimento específico da plataforma.

Clone o código-fonte e inicialize

Instale o desenvolvimento Desktop com carga de trabalho C++ para Visual Studio 2022. O Visual Studio 2019 também é suportado.
Instale o CMake. Certifique-se de que está no seu PATH entrando a cmake -version partir de um prompt de comando.
Abra uma linha de comandos ou a shell do Git Bash. Execute os seguintes comandos para clonar a versão mais recente da ramificação de visualização pública do repositório GitHub do 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
```
Espere que esta operação demore vários minutos a concluir.
Execute os seguintes comandos do azure-iot-sdk-c diretório para criar um cmake subdiretório e vá para a cmake pasta:
```
mkdir cmake
cd cmake
cmake ..
```
Se o CMake não conseguir encontrar o 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.

Depois que a compilação for bem-sucedida, 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, edite 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 .

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

Procure 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 connectionString o valor da constante pela cadeia de conexão do dispositivo que você salvou na seção Registrar um dispositivo do início rápido para enviar telemetria.

Encontre a linha de código que chama IoTHubDeviceClient_LL_SetConnectionStatusCallback para registrar uma função de retorno de chamada de status de conexão antes do loop de mensagem de envio. Adicione 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 IoTHubDeviceClient_LL_EnablePolicyConfiguration função habilita políticas para recursos específicos do Hub IoT que são configurados por meio de gêmeos de dispositivo. Depois de ativar POLICY_CONFIGURATION_DISTRIBUTED_TRACING usando a linha extra de código, o comportamento de rastreamento do dispositivo refletirá as alterações de rastreamento distribuído feitas no gêmeo do dispositivo.

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

    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

Vá para o iothub_ll_telemetry_sample diretório do projeto a partir do diretório CMake (azure-iot-sdk-c/cmake) que você criou anteriormente e compile o exemplo:
```
cd iothub_client/samples/iothub_ll_telemetry_sample
cmake --build . --target iothub_ll_telemetry_sample --config Debug
```
Execute a aplicação. O dispositivo envia telemetria que suporta rastreamento distribuído.
```
Debug/iothub_ll_telemetry_sample.exe
```
Mantenha o aplicativo em execução. Você pode observar as mensagens 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 C SDK é mais complexo. Nós não recomendamos.

Primeiro, você deve implementar todas as primitivas do protocolo do Hub IoT em suas mensagens seguindo o guia do desenvolvedor Criar e ler mensagens do Hub IoT. Em seguida, edite as propriedades do protocolo nas mensagens 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 Unix time-stamp. Como exemplo, consulte a implementação no C SDK.
Para 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óximos passos

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

Partilhar via