Compartilhar via

Como depurar funções definidas pelo usuário em Gêmeos Digitais do Azure

  • Artigo

Importante

Uma nova versão do serviço dos Gêmeos Digitais do Azure foi lançada. À luz das funcionalidades expandidas do novo serviço, o serviço original dos Gêmeos Digitais do Azure (descrito neste conjunto de documentação) foi desativado.

Para exibir a documentação do novo serviço, visite a Documentação ativa dos Gêmeos Digitais do Azure.

Este artigo resume como diagnosticar e depurar funções definidas pelo usuário nos Gêmeos Digitais do Azure. Em seguida, ele identifica alguns dos cenários mais comuns encontrados ao depurá-las.

Dica

Leia Como configurar monitoramento e registro em log para saber mais sobre a configuração de ferramentas de depuração em Gêmeos Digitais do Azure usando Logs de Atividades, Logs de Diagnóstico e Azure Monitor.

Problemas de depuração

Saber como diagnosticar problemas nos Gêmeos Digitais do Azure permite que você analise problemas com eficiência, identifique as causas dos problemas e forneça soluções apropriadas para eles.

Uma variedade de ferramentas de log, análise e diagnóstico são fornecidas para esse fim.

Habilitar o registro em log para sua instância

Os Gêmeos Digitais do Azure dão suporte a registro em log, monitoramento e análise robustos. Os desenvolvedores de soluções podem usar logs do Azure Monitor, logs de diagnóstico, logs de atividades e outros serviços para dar suporte às complexas necessidades de monitoramento de um aplicativo IoT. As opções de registro em log podem ser combinadas para consultar ou exibir registros em vários serviços e para fornecer cobertura de registro em log granular para muitos serviços.

Depois de configurado, você poderá selecionar todas as categorias de log, métricas e usar workspaces avançados do Log Analytics do Azure Monitor para dar suporte aos esforços de depuração.

Sensor de telemetria de rastreamento

Para rastrear telemetria do sensor, verifique se as configurações de diagnóstico estão habilitadas para sua instância dos Gêmeos Digitais do Azure. Em seguida, verifique se todas as categorias de log desejadas estão selecionadas. Por fim, confirme se os logs desejados estão sendo enviados para logs do Azure Monitor.

Para corresponder a uma mensagem de telemetria do sensor para seus respectivos logs, você pode especificar uma ID de Correlação nos dados de evento que estão sendo enviados. Para fazer isso, defina a propriedade x-ms-client-request-id para um GUID.

Depois de enviar telemetria, abra a análise de log do Azure Monitor para consultar logs usando a ID de correlação definida:

AzureDiagnostics
| where CorrelationId == 'YOUR_CORRELATION_IDENTIFIER'
Valor da consulta Substitua por
YOUR_CORRELATION_IDENTIFIER A ID de Correlação que foi especificada nos dados de evento

Para ler todas as consultas de logs de telemetria recentes:

AzureDiagnostics
| order by CorrelationId desc

Se você habilitar o registro em log para sua função definida pelo usuário, esses logs aparecerão na instância do log analytics com a categoria UserDefinedFunction. Para recuperá-los, insira a seguinte condição de consulta no log analytics:

AzureDiagnostics
| where Category == 'UserDefinedFunction'

Para obter mais informações sobre operações de consulta avançada, leia Introdução às consultas.

Identificar problemas comuns

O diagnóstico e a identificação de problemas comuns são importantes durante a solução de problemas em sua solução. Vários problemas que são comumente encontrados ao desenvolver funções definidas pelo usuário estão resumidos nas subseções a seguir.

Nos exemplos a seguir, YOUR_MANAGEMENT_API_URL refere-se ao URI de APIs de Gêmeos Digitais:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0
Nome Substitua por
NOME_DA_SUA_INSTÂNCIA O nome da sua instância de Gêmeos Digitais do Azure
SUA_LOCALIZAÇÃO A região em que sua instância está hospedada

Verificar se uma atribuição de função foi criada

Sem uma atribuição de função criada na API de Gerenciamento, a função definida pelo usuário não tem acesso para executar nenhuma ação, como enviar notificações, recuperar metadados e definir valores computadores na topologia.

Verifique se existe uma atribuição de função para sua função definida pelo usuário por meio de sua API de Gerenciamento:

GET YOUR_MANAGEMENT_API_URL/roleassignments?path=/&traverse=Down&objectId=YOUR_USER_DEFINED_FUNCTION_ID
Valor do parâmetro Substitua por
YOUR_USER_DEFINED_FUNCTION_ID A ID da função definida pelo usuário para a qual serão recuperadas as atribuições de função

Leia Como criar uma atribuição de função para a função definida pelo usuário, se nenhuma atribuição de função existir.

Verifique se o correspondente funciona para a telemetria de um sensor

Com a chamada a seguir à API de Gerenciamento das instâncias dos Gêmeos Digitais do Azure, você poderá determinar se um determinado correspondente se aplica para o sensor determinado.

GET YOUR_MANAGEMENT_API_URL/matchers/YOUR_MATCHER_IDENTIFIER/evaluate/YOUR_SENSOR_IDENTIFIER?enableLogging=true
Parâmetro Substitua por
YOUR_MATCHER_IDENTIFIER A ID do correspondente que você deseja avaliar
YOUR_SENSOR_IDENTIFIER A ID do sensor que você deseja avaliar

Resposta:

{
    "success": true,
    "logs": [
        "$.dataType: \"Motion\" Equals \"Motion\" => True"
    ]
}

Verifique o que um sensor dispara

Com a seguinte chamada para as APIs de Gerenciamento dos Gêmeos Digitais do Azure, você pode determinar os identificadores de suas funções definidas pelo usuário disparadas pela telemetria de entrada do sensor determinado:

GET YOUR_MANAGEMENT_API_URL/sensors/YOUR_SENSOR_IDENTIFIER/matchers?includes=UserDefinedFunctions
Parâmetro Substitua por
YOUR_SENSOR_IDENTIFIER A ID do sensor para enviar telemetria

Resposta:

[
    {
        "id": "48a64768-797e-4832-86dd-de625f5f3fd9",
        "name": "MotionMatcher",
        "spaceId": "2117b3e1-b6ce-42c1-9b97-0158bef59eb7",
        "conditions": [
            {
                "id": "024a067a-414f-415b-8424-7df61392541e",
                "target": "Sensor",
                "path": "$.dataType",
                "value": "\"Motion\"",
                "comparison": "Equals"
            }
        ],
        "userDefinedFunctions": [
            {
                "id": "373d03c5-d567-4e24-a7dc-f993460120fc",
                "spaceId": "2117b3e1-b6ce-42c1-9b97-0158bef59eb7",
                "name": "Motion User-Defined Function",
                "disabled": false
            }
        ]
    }
]

Problema com o recebimento de notificações

Quando você não estiver recebendo notificações da função definida pelo usuário disparada, confirme que seu parâmetro de tipo de objeto de topologia corresponde ao tipo de identificador que está sendo usado.

Incorreto Exemplo:

var customNotification = {
    Message: 'Custom notification that will not work'
};

sendNotification(telemetry.SensorId, "Space", JSON.stringify(customNotification));

Esse cenário ocorre porque o identificador usado refere-se a um sensor, enquanto o tipo de objeto de topologia especificado é Space.

Correto Exemplo:

var customNotification = {
    Message: 'Custom notification that will work'
};

sendNotification(telemetry.SensorId, "Sensor", JSON.stringify(customNotification));

A maneira mais fácil de não ter esse problema é usar o método Notify no objeto de metadados.

Exemplo:

function process(telemetry, executionContext) {
    var sensorMetadata = getSensorMetadata(telemetry.SensorId);

    var customNotification = {
        Message: 'Custom notification'
    };

    // Short-hand for above methods where object type is known from metadata.
    sensorMetadata.Notify(JSON.stringify(customNotification));
}

Exceções de diagnóstico comuns

Se habilitar as configurações de diagnóstico, você poderá encontrar estas exceções comuns:

  1. Limitação: se sua função definida pelo usuário exceder os limites da taxa de execução descritos no artigo Limites de serviço, ela será limitada. Nenhuma outra operação será executada com êxito até que os limites de limitação expirem.

  2. Dados Não Encontrados: se sua função definida pelo usuário tentar acessar metadados que não existem, a operação falhará.

  3. Não Autorizado: se sua função definida pelo usuário não tiver uma atribuição de função definida ou não tiver permissões suficientes para acessar alguns metadados da topologia, a operação falhará.

Próximas etapas