Telemetria e solução de problemas

A Análise Espacial inclui um conjunto de recursos para monitorar a integridade do sistema e ajudar a diagnosticar problemas.

Habilitar visualizações

Para habilitar uma visualização dos eventos de Insights da IA em um quadro de vídeo, você precisa usar a versão .debug de uma operação de Análise Espacial em um computador desktop ou VM do Azure. A visualização não é possível em dispositivos do Azure Stack Edge. Há quatro operações de depuração disponíveis.

Se o dispositivo for um computador da área de trabalho local ou uma VM de GPU do Azure (com a área de trabalho remota habilitada), você poderá alternar para a versão .debug de qualquer operação e visualizar a saída.

1. Abra o desktop localmente ou usando um cliente de área de trabalho remota no computador host que executa a análise espacial.

2. No terminal, execute xhost +

3. Atualize o manifesto de implantação no módulo spaceanalytics com o valor da variável de ambiente DISPLAY. Você pode encontrar seu valor executando echo $DISPLAY no terminal no computador host.

   "env": {        
       "DISPLAY": {
           "value": ":11"
           }
   }
   

4. Atualize o grafo no manifesto de implantação que você deseja executar no modo de depuração. No exemplo a seguir, atualizamos a operationId to cognitiveservices.vision.spatialanalysis-personcrossingpolygon.debug. Um novo parâmetro VISUALIZER_NODE_CONFIG é necessário para habilitar a janela do visualizador. Todas as operações estão disponíveis na variante de depuração. Ao usar nós compartilhados, use a operação cognitivaservices.vision.spatialanalysis.debug e adicione VISUALIZER_NODE_CONFIG aos parâmetros da instância.

   "zonecrossing": {
        "operationId" : "cognitiveservices.vision.spatialanalysis-personcrossingpolygon.debug",
        "version": 1,
        "enabled": true,
        "parameters": {
            "VIDEO_URL": "Replace http url here",
            "VIDEO_SOURCE_ID": "zonecrossingcamera",
            "VIDEO_IS_LIVE": false,
           "VIDEO_DECODE_GPU_INDEX": 0,
            "DETECTOR_NODE_CONFIG": "{ \"gpu_index\": 0 }",
           "CAMERACALIBRATOR_NODE_CONFIG": "{ \"gpu_index\": 0}",
           "VISUALIZER_NODE_CONFIG": "{ \"show_debug_video\": true }",
            "SPACEANALYTICS_CONFIG": "{\"zones\":[{\"name\":\"queue\",\"polygon\":[[0.3,0.3],[0.3,0.9],[0.6,0.9],[0.6,0.3],[0.3,0.3]], \"threshold\":35.0}]}"
        }
   }
   

5. Faça a reimplantação e você verá a janela do visualizador no computador host

6. Após a conclusão da implantação, talvez seja necessário copiar o arquivo .Xauthority do computador host para o contêiner e reiniciá-lo. No exemplo abaixo, peopleanalytics é o nome do contêiner no computador host.

   sudo docker cp $XAUTHORITY peopleanalytics:/root/.Xauthority
   sudo docker stop peopleanalytics
   sudo docker start peopleanalytics
   xhost +
   

Coletar telemetria de integridade do sistema

O Telegraf é uma imagem de software livre que funciona com Análise Espacial e está disponível no Microsoft Container Registry. Ele usa as entradas a seguir e as envia para o Azure Monitor. O módulo Telegraf pode ser compilado com entradas e saídas personalizadas desejadas. A configuração do módulo Telegraf na Análise Espacial faz parte do manifesto de implantação (link acima). Esse módulo é opcional e pode ser removido do manifesto se você não precisar dele.

Entradas:

• Métricas de Análise Espacial
• Métricas de disco
• Métricas de CPU
• Métricas do Docker
• Métricas de GPU

Saídas:

• Azure Monitor

O módulo Telegraf da Análise Espacial fornecido publicará todos os dados de telemetria emitidos pelo contêiner da Análise Espacial no Azure Monitor. Confira o Azure Monitor para obter informações sobre como adicionar o Azure Monitor à sua assinatura.

Após a configuração do Azure Monitor, você precisará criar credenciais que permitam que o módulo envie telemetria. Você pode usar o portal do Azure para criar uma Entidade de Serviço ou usar o comando da CLI do Azure abaixo para criar uma.

Observação

Esse comando exige que você tenha privilégios de Proprietário na assinatura.

# Find your Azure IoT Hub resource ID by running this command. The resource ID  should start with something like 
# "/subscriptions/b60d6458-1234-4be4-9885-c7e73af9ced8/resourceGroups/..."
az iot hub list

# Create a Service Principal with `Monitoring Metrics Publisher` role in the IoTHub resource:
# Save the output from this command. The values will be used in the deployment manifest. The password won't be shown again so make sure to write it down
az ad sp create-for-rbac --role="Monitoring Metrics Publisher" --name "<principal name>" --scopes="<resource ID of IoT Hub>"

No manifesto de implantação do seu dispositivo do Azure Stack Edge, computador desktop ou VM do Azure com GPU, procure o módulo Telegraf e substitua os seguintes valores pelas informações da Entidade de Serviço da etapa anterior e faça a reimplantação.

"Telegraf": { 
  "settings": {
  "image":   "mcr.microsoft.com/azure-cognitive-services/vision/spatial-analysis/Telegraf:1.0",
  "createOptions":   "{\"HostConfig\":{\"Runtime\":\"nvidia\",\"NetworkMode\":\"azure-iot-edge\",\"Memory\":33554432,\"Binds\":[\"/var/run/docker.sock:/var/run/docker.sock\"]}}"
},
"type": "docker",
"env": {
    "AZURE_TENANT_ID": {
        "value": "<Tenant Id>"
    },
    "AZURE_CLIENT_ID": {
        "value": "Application Id"
    },
    "AZURE_CLIENT_SECRET": {
        "value": "<Password>"
    },
    "region": {
        "value": "<Region>"
    },
    "resource_id": {
        "value": "/subscriptions/{subscriptionId}/resourceGroups/{resoureGroupName}/providers/Microsoft.Devices/IotHubs/{IotHub}"
    },
...

Depois que o módulo Telegraf é implantado, as métricas relatadas podem ser acessadas por meio do serviço Azure Monitor ou selecionando Monitoramento no Hub IoT no portal do Azure.

Eventos de integridade do sistema

Nome do evento	Descrição
archon_exit	Enviado quando um usuário altera o status do módulo de Análise Espacial de em execução para interrompido.
archon_error	Enviado quando ocorre uma falha em qualquer um dos processos dentro do contêiner. Esse é um evento crítico.
InputRate	A taxa na qual o grafo processa a entrada de vídeo. Relatado a cada cinco minutos.
OutputRate	A taxa na qual o grafo gera insights de IA. Relatado a cada cinco minutos.
archon_allGraphsStarted	Enviado quando todos os gráficos concluem a inicialização.
archon_configchange	Enviado quando uma configuração de grafo é alterada.
archon_graphCreationFailed	Enviado quando o grafo com o graphId relatado não é iniciado.
archon_graphCreationSuccess	Enviado quando o grafo com o graphId relatado é iniciado com sucesso.
archon_graphCleanup	Enviado quando o grafo com o graphId relatado é limpo e encerrado.
archon_graphHeartbeat	Pulsação enviada a cada minuto para cada grafo de uma habilidade.
archon_apiKeyAuthFail	Enviado quando a chave do recurso Vision falha ao autenticar o contêiner por mais de 24 horas, devido aos seguintes motivos: Fora da Cota, Inválido, Offline.
VideoIngesterHeartbeat	Enviado a cada hora para indicar que o vídeo é transmitido da fonte de vídeo, com o número de erros naquela hora. Relatado para cada grafo.
VideoIngesterState	Relata Interrompido ou Iniciado para streaming de vídeo. Relatado para cada grafo.

Solução de problemas de um Dispositivo de IoT Edge

Você pode usar a ferramenta de linha de comando iotedge para verificar o status e os logs dos módulos em execução. Por exemplo:

• iotedge list: relata uma lista de módulos em execução. Você pode verificar se há erros com o iotedge logs edgeAgent. Se o iotedge travar, você pode tentar reiniciá-lo com iotedge restart edgeAgent
• iotedge logs <module-name>
• iotedge restart <module-name> para reiniciar um módulo específico

Coletar arquivos de log com o contêiner de diagnóstico

A Análise Espacial gera logs de depuração do Docker que você pode usar para diagnosticar problemas de runtime ou incluir tíquetes de suporte. O módulo de diagnóstico de Análise Espacial está disponível no Microsoft Container Registry para download. No arquivo de implantação de manifesto para o Dispositivo do Azure Stack Edge, o computador desktop ou o VM do Azure com GPU, procure o módulo de diagnóstico.

Na seção "env", adicione a seguinte configuração:

"diagnostics": {  
  "settings": {
  "image":   "mcr.microsoft.com/azure-cognitive-services/vision/spatial-analysis/diagnostics:1.0",
  "createOptions":   "{\"HostConfig\":{\"Mounts\":[{\"Target\":\"/usr/bin/docker\",\"Source\":\"/home/data/docker\",\"Type\":\"bind\"},{\"Target\":\"/var/run\",\"Source\":\"/run\",\"Type\":\"bind\"}],\"LogConfig\":{\"Config\":{\"max-size\":\"500m\"}}}}"
  }

Para otimizar os logs carregados em um ponto de extremidade remoto, como o Armazenamento de Blobs do Azure, recomendamos que você mantenha um tamanho de arquivo pequeno. Confira o exemplo abaixo para obter a configuração de logs do Docker recomendada.

{
    "HostConfig": {
        "LogConfig": {
            "Config": {
                "max-size": "500m",
                "max-file": "1000"
            }
        }
    }
}

Configurar o nível do log

A configuração do nível de log permite que você controle o detalhamento dos logs gerados. Os níveis de log com suporte são: none, verbose, info, warning e error. O nível detalhado de log padrão para os nós e a plataforma é info.

Os níveis de log podem ser modificados globalmente definindo a variável de ambiente ARCHON_LOG_LEVEL para um dos valores permitidos. Ele também pode ser definido por meio do documento do módulo gêmeo do IoT Edge, seja globalmente, para todas as habilidades implantadas ou para cada habilidade específica, definindo os valores de platformLogLevel e nodesLogLevel conforme mostrado abaixo.

{
    "version": 1,
    "properties": {
        "desired": {
            "globalSettings": {
                "platformLogLevel": "verbose"
            },
            "graphs": {
                "samplegraph": {
                    "nodesLogLevel": "verbose",
                    "platformLogLevel": "verbose"
                }
            }
        }
    }
}

coletando logs

Observação

O módulo diagnostics não afeta o registro em log, ele só ajuda a coletar, filtrar e carregar os logs existentes. Você deve ter a versão 1.40 ou superior da API do Docker para usar esse módulo.

O arquivo de manifesto de implantação de exemplo para o dispositivo do Azure Stack Edge, o computador desktop ou a VM do Azure com GPU inclui um módulo chamado diagnostics que coleta e carrega logs. Esse módulo é desabilitado por padrão e deve ser habilitado por meio da configuração do módulo do IoT Edge quando você precisa acessar os logs.

A coleção diagnostics é sob demanda e controlada por meio de um método direto do IoT Edge e pode enviar logs para um Armazenamento de Blobs do Azure.

Configurar destinos de upload de diagnóstico

No portal do IoT Edge, selecione o dispositivo e, depois, o módulo diagnóstico. No arquivo de manifesto de implantação de exemplo para o dispositivo do Azure Stack Edge, os computadores desktop ou a VM do Azure com GPU, procure a seção Variáveis de Ambiente para diagnóstico, chamado env, e adicione as seguintes informações:

Configurar upload para o Armazenamento de Blobs do Azure

1. Crie a própria conta de Armazenamento de Blobs do Azure, caso ainda não tenha feito isso.
2. Obtenha a Cadeia de Conexão da sua conta de armazenamento por meio do portal do Azure. Ela está localizada em Chaves de Acesso.
3. Os logs de Análise Espacial são automaticamente carregados em um contêiner de Armazenamento de Blobs chamado rtcvlogs com o seguinte formato de nome de arquivo: {CONTAINER_NAME}/{START_TIME}-{END_TIME}-{QUERY_TIME}.log.

"env":{
    "IOTEDGE_WORKLOADURI":"fd://iotedge.socket",
    "AZURE_STORAGE_CONNECTION_STRING":"XXXXXX",   //from the Azure Blob Storage account
    "ARCHON_LOG_LEVEL":"info"
}

Como carregar logs de Análise Espacial

Os logs são carregados sob demanda com o método getRTCVLogs do IoT Edge, no módulo diagnostics.

1. Acesse a página do portal do Hub IoT, selecione Dispositivos de Bordae escolha o dispositivo e o módulo de diagnóstico.
2. Vá para a página de detalhes do módulo e selecione a guia método direto.
3. Digite getRTCVLogs em Nome do Método e uma cadeia de caracteres de formato JSON no conteúdo. Você pode inserir {}, que é um conteúdo vazio.
4. Defina os tempos limite de conexão e método e selecione Chamar método.
5. Selecione o contêiner de destino e crie uma cadeia de caracteres JSON de conteúdo usando os parâmetros descritos na seção de Sintaxe de registro em log. Selecione Chamar método para realizar a solicitação.

Observação

A invocação do método getRTCVLogs com um conteúdo vazio retornará uma lista de todos os contêineres implantados no dispositivo. O nome do método diferencia maiúsculas de minúsculas. Você receberá um erro 501 se um nome de método incorreto for fornecido.

Sintaxe de registro em log

A tabela abaixo lista os parâmetros que você pode usar ao consultar logs.

Palavra-chave	Descrição	Valor padrão
StartTime	Hora de início dos logs desejados, UTC em milissegundos.	-1, o início do runtime do contêiner. Quando [-1.-1] é usado como um intervalo de tempo, a API retorna logs da última hora.
EndTime	Hora de término dos logs desejados, UTC em milissegundos.	-1, a hora atual. Quando o intervalo de tempo [-1.-1] é usado, a API retorna logs da última hora.
ContainerId	Contêiner de destino para a busca de logs.	null, quando não há nenhuma ID de contêiner. A API retorna todas as informações de contêineres disponíveis com IDs.
DoPost	Realiza a operação de atualização. Ao ser definido como false, ele executa a operação solicitada e retorna o tamanho do carregamento sem executá-lo. Quando definido como true, ele iniciará o carregamento assíncrono dos registros selecionados	false, não faça o upload.
Restrição	Indica quantas linhas de logs devem ser carregadas por lote	1000, Use esse parâmetro para ajustar a velocidade da postagem.
Filtros	Filtra os logs a serem carregados	null, os filtros podem ser especificados como pares de chave-valor com base na estrutura de registros da Análise Espacial: [UTC, LocalTime, LOGLEVEL,PID, CLASS, DATA]. Por exemplo: {"TimeFilter":[-1,1573255761112]}, {"TimeFilter":[-1,1573255761112]}, {"CLASS":["myNode"]

A tabela a seguir lista os atributos na resposta da consulta.

Palavra-chave	Descrição
DoPost	Verdadeiro ou falso. Indica se os logs foram carregados ou não. Quando você optar por não carregar os logs, a API retornará informações de forma síncrona. Quando você optar por carregar os logs, a API retornará 200 se a solicitação for válida e começará a carregar logs de forma assíncrona.
TimeFilter	Filtro de tempo aplicado aos logs.
ValueFilters	Filtros de palavras-chave aplicados aos registros.
TimeStamp	Hora de início da execução do método.
ContainerId	ID do contêiner de destino.
FetchCounter	Número total de linhas de log.
FetchSizeInByte	Quantidade total de dados de log em bytes.
MatchCounter	Número válido de linhas de log.
MatchSizeInByte	Quantidade válida de dados de log em bytes.
FilterCount	Número total de linhas de log após a aplicação do filtro.
FilterSizeInByte	Número total de linhas de log em bytes após a aplicação do filtro.
FetchLogsDurationInMiliSec	Busca a duração da operação.
PaseLogsDurationInMiliSec	Filtra a duração da operação.
PostLogsDurationInMiliSec	Posta a duração da operação.

Solicitação de exemplo

{
    "StartTime": -1,
    "EndTime": -1,
    "ContainerId": "5fa17e4d8056e8d16a5a998318716a77becc01b36fde25b3de9fde98a64bf29b",
    "DoPost": false,
    "Filters": null
}

Exemplo de resposta

{
    "status": 200,
    "payload": {
        "DoPost": false,
        "TimeFilter": [-1, 1581310339411],
        "ValueFilters": {},
        "Metas": {
            "TimeStamp": "2020-02-10T04:52:19.4365389+00:00",
            "ContainerId": "5fa17e4d8056e8d16a5a998318716a77becc01b36fde25b3de9fde98a64bf29b",
            "FetchCounter": 61,
            "FetchSizeInByte": 20470,
            "MatchCounter": 61,
            "MatchSizeInByte": 20470,
            "FilterCount": 61,
            "FilterSizeInByte": 20470,
            "FetchLogsDurationInMiliSec": 0,
            "PaseLogsDurationInMiliSec": 0,
            "PostLogsDurationInMiliSec": 0
        }
    }
}

Verifique as linhas, os horários e tamanhos do log de busca. Se essas configurações forem boas, substitua DoPost por true e isso efetuará push dos logs com os mesmos filtros para os destinos.

Você pode exportar os logs do Armazenamento de Blobs do Azure ao solucionar problemas.

Solução de problemas do dispositivo do Azure Stack Edge

A seção a seguir é fornecida para obter ajuda com a depuração e a verificação do status do dispositivo do Azure Stack Edge.

Acessar o Ponto de Extremidade de API do Kubernetes. 

1. Na IU local do dispositivo, acesse a página Dispositivos.
2. Nos Pontos de extremidade do dispositivo, copie o ponto de extremidade de serviço da API do Kubernetes. Esse ponto de extremidade é uma cadeia de caracteres no seguinte formato: https://compute..[device-IP-address].
3. Salve a cadeia de caracteres do ponto de extremidade. Você usará isso mais tarde ao configurar kubectl para acessar o cluster do Kubernetes.

Conectar-se à interface do PowerShell

Remotamente, conecte-se usando um cliente do Windows. Depois que o cluster do Kubernetes for criado, você poderá gerenciar os aplicativos por meio desse cluster. Você precisará se conectar à interface do PowerShell do dispositivo. Dependendo do sistema operacional do cliente, os procedimentos para se conectar remotamente ao dispositivo podem ser diferentes. As etapas a seguir são para um cliente do Windows executando o PowerShell.

Dica

• Antes de começar, verifique se o cliente do Windows está executando o Windows PowerShell 5.0 ou posterior.
• O PowerShell também está disponível no Linux.

1. Execute uma sessão do Windows PowerShell como Administrador.

   Verifique se o serviço de Gerenciamento Remoto do Windows está em execução no cliente. No prompt de comando, digite winrm quickconfig.

2. Atribua uma variável ao endereço IP do dispositivo. Por exemplo, $ip = "<device-ip-address>".

3. Use o comando a seguir para adicionar o endereço IP do dispositivo à lista de hosts confiáveis do cliente.

   Set-Item WSMan:\localhost\Client\TrustedHosts $ip -Concatenate -Force
   

4. Inicie uma sessão do Windows PowerShell no dispositivo.

   Enter-PSSession -ComputerName $ip -Credential $ip\EdgeUser -ConfigurationName Minishell
   

5. Forneça a senha quando solicitada. Use a mesma senha usada para entrar na interface da Web local. A senha padrão da interface da Web local é Password1.

Acesse o cluster do Kubernetes

Depois que o cluster do Kubernetes é criado, você pode usar a ferramenta de linha de comando kubectl para acessar o cluster.

1. Crie um namespace.

   New-HcsKubernetesNamespace -Namespace
   

2. Crie um usuário e obtenha um arquivo de configuração. Esse comando gera informações de configuração para o cluster do Kubernetes. Copie essas informações e salve-as em um arquivo chamado config. Não o salve como uma extensão de arquivo.

   New-HcsKubernetesUser -UserName
   

3. Adicione o arquivo config à pasta .kube no perfil do usuário no computador local.

4. Associe o namespace ao usuário que você criou.

   Grant-HcsKubernetesNamespaceAccess -Namespace -UserName
   

5. Instale kubectl no seu cliente do Windows usando o seguinte comando:

   curl https://storage.googleapis.com/kubernetesrelease/release/v1.15.2/bin/windows/amd64/kubectl.exe -O kubectl.exe
   

6. Adicione uma entrada DNS ao arquivo de hosts no sistema.

   1. Execute o Bloco de notas como administrador e abra o arquivo hosts localizado em C:\windows\system32\drivers\etc\hosts.
   2. Crie uma entrada no arquivo de hosts com o endereço IP do dispositivo e o domínio DNS obtidos na página do Dispositivo na IU local. O ponto de extremidade que deve ser usado será semelhante a: https://compute.asedevice.microsoftdatabox.com/10.100.10.10.

7. Verifique se você pode se conectar aos pods do Kubernetes.

   kubectl get pods -n "iotedge"
   

Para obter logs de contêiner, execute o seguinte comando:

kubectl logs <pod-name> -n <namespace> --all-containers

Comandos úteis

Comando	Descrição
Get-HcsKubernetesUserConfig -AseUser	Gera um arquivo de configuração do Kubernetes. Ao usar o comando, copie as informações em um arquivo chamado config. Não salve o arquivo com uma extensão de arquivo.
Get-HcsApplianceInfo	Retorna informações sobre o dispositivo.
Enable-HcsSupportAccess	Gera credenciais de acesso para iniciar uma sessão de suporte.

Como arquivar um tíquete de suporte para Análise Espacial

Se precisar de mais suporte para encontrar uma solução para um problema que está tendo com o contêiner de Análise Espacial, siga as etapas abaixo para preencher e enviar um tíquete de suporte. Nossa equipe entrará em contato com você com mais diretrizes.

Preencha as informações básicas

Crie um tíquete de suporte na página Nova solicitação de suporte. Siga os prompts para preencher os seguintes parâmetros:

1. Defina o Tipo de Problema como Technical.
2. Selecione a assinatura que você está utilizando para implantar o contêiner da Análise Espacial.
3. Selecione My services e selecione Azure AI services como o serviço.
4. Selecione o recurso que você está utilizando para implantar o contêiner da Análise Espacial.
5. Escreva uma breve descrição detalhando o problema que você está enfrentando.
6. Selecione Spatial Analysis como o tipo de problema.
7. Selecione o subtipo apropriado no menu suspenso.
8. Selecione Avançar: Soluções e avance para a próxima página.

Soluções recomendadas

A próxima fase oferecerá as soluções recomendadas para o tipo de problema que você selecionou. Essas soluções resolverão os problemas mais comuns, mas se elas não forem úteis para sua solução, selecione Avançar: Detalhes e avance para a próxima etapa.

Detalhes

Nessa página, adicione alguns detalhes adicionais sobre o problema que você está enfrentando. Lembre-se de incluir o máximo de detalhes possível, pois isso ajudará nossos engenheiros a restringir melhor o problema. Inclua seu método de contato preferencial e a severidade do problema para que possamos entrar em contato com você, selecione Avançar: Examinar + Criar e avance para a próxima etapa.

Examinar e criar

Examine os detalhes da solicitação de suporte para garantir que tudo seja preciso e represente o problema com eficiência. Quando estiver pronto, selecione Criar para enviar o tíquete para a nossa equipe! Você receberá uma confirmação por email quando seu tíquete for recebido, e nossa equipe entrará em contato com você o mais rápido possível. Você pode ver o status do tíquete no portal do Azure.

Próximas etapas

• Implantar um aplicativo Web de Contagem de Pessoas
• Configurar operações de análise espacial
• Guia de posicionamento da câmera
• Guia de posicionamento de zona e de linha