Skip to main content

Logger de mensagens de facial

O plugin Logger de mensagens de facial (faciallogger) registra em arquivo de log as mensagens trocadas entre o ACCELERO e o gateway facial durante o cadastro e a remoção de templates faciais. Ele existe exclusivamente para diagnóstico técnico do fluxo de comunicação com os dispositivos de reconhecimento facial.

Ferramenta de diagnóstico técnico (uso interno)

Este plugin é uma ferramenta interna de debug, sem interface de usuário, telas de configuração ou itens de menu. Ele apenas escreve um arquivo de log no servidor. Deve ser instalado pela equipe técnica da IONGRADE quando há necessidade de investigar problemas no envio de templates faciais — e desinstalado depois. Não é um recurso voltado ao cliente final.

Disponibilidade

Disponibilizado como plugin (faciallogger), instalado e habilitado pela equipe técnica da IONGRADE. Por ser uma ferramenta de diagnóstico, normalmente é ativado de forma temporária durante uma investigação.

Compatibilidade

Versão atual do plugin: 0.0.2 — compatível com ACCELERO 2.16.0, 2.16.1 e 2.16.2.

O que o plugin faz​

Quando instalado e ativo, o plugin sobe um processo de segundo plano (long-running) que escuta o barramento de mensagens MQTT do ACCELERO e grava em log cada mensagem relacionada a templates faciais. Nenhuma ação do operador é necessária — o registro acontece automaticamente em segundo plano.

FuncionalidadeO que acontece no ACCELERO
Log de comandos enviadosCada comando de cadastro/remoção de template facial enviado ao gateway é registrado, com o tipo do comando, a pessoa e o dispositivo de destino
Log de respostas recebidasCada resposta do gateway é registrada, com o tipo, o identificador da mensagem e o status retornado
Para que serve

Permite à equipe técnica correlacionar comandos enviados e respostas recebidas pelo identificador da mensagem (msgID), facilitando o diagnóstico de falhas no cadastro ou na remoção de templates faciais em dispositivos.

Como funciona​

O plugin registra um processo de longa duração chamado facial_messages_logger, iniciado junto com o subsistema de processamento assíncrono do ACCELERO (evento async_processor_startup).

Esse processo conecta-se ao broker MQTT como cliente facial_logger e assina dois padrões de tópico:

Tópico assinadoDireçãoConteúdo
+/+/+/messagesSaída (ACCELERO → gateway)Comandos de cadastro/remoção de template
+/+/+/responseEntrada (gateway → ACCELERO)Respostas do gateway aos comandos

Para cada mensagem recebida, o plugin identifica o tipo do comando (campo command ou cmd do payload) e grava uma entrada no log:

  • Mensagens de saída (messages) — para cada par dispositivo/mensagem, registra um evento Command com o tipo do comando, o ID da pessoa (pesID), o ID da mensagem (msgID) e o ID do dispositivo (deviceID).
  • Mensagens de entrada (response) — registra um evento Response com o tipo, o ID da mensagem (msgID) e o status retornado pelo gateway.

Mensagens cujo payload não seja um JSON válido, ou que não contenham um tipo de comando, são ignoradas.

Arquivo de log​

O plugin grava as entradas no arquivo de log do ACCELERO facial_logger.log.json, no nível Debug (canal facial_logger). É nesse arquivo que a equipe técnica consulta o histórico de comandos e respostas para investigação.

EventoCampos registrados
Command (saída)type, pesID, msgID, deviceID
Response (entrada)type, msgID, status
TODO: Adicionar Screenshot

Exemplo de trecho do arquivo facial_logger.log.json mostrando um evento Command (saída) e o respectivo evento Response (entrada) correlacionados pelo mesmo msgID.

Volume de log

Por gravar todas as mensagens de templates faciais em nível Debug, o arquivo pode crescer rapidamente em ambientes com muitos dispositivos ou cadastros. Mantenha o plugin ativo apenas durante a investigação e desinstale-o ao concluir.

Instalação e remoção​

A instalação e a remoção do plugin reiniciam os serviços do ACCELERO (Accelero::restartServices()) para que o processo de logging seja iniciado ou encerrado.

  • Instalação — após instalar, os serviços são reiniciados e o processo facial_messages_logger passa a registrar as mensagens.
  • Remoção — ao desinstalar, os serviços são reiniciados novamente e o logging é interrompido.
Sem configuração

O plugin não possui tela de configuração, campos adicionais nas entidades nem itens de menu. Seu comportamento é fixo: assinar os tópicos MQTT e gravar o log.

Casos de uso​

Investigar falha no cadastro de template facial​

  1. Solicitar à IONGRADE a instalação do plugin faciallogger.
  2. Reproduzir o cadastro do template facial da pessoa no dispositivo afetado.
  3. Consultar o arquivo facial_logger.log.json e localizar o evento Command correspondente (pelo pesID e deviceID).
  4. Verificar se existe um evento Response com o mesmo msgID e qual o status retornado pelo gateway.
  5. Após a investigação, solicitar a remoção do plugin.

Boas práticas​

  • Uso temporário: ative o plugin apenas durante a investigação e remova-o ao concluir, para evitar crescimento desnecessário do log.
  • Compatibilidade de versão: confirme que a versão do ACCELERO está entre 2.16.0 e 2.16.2 antes de instalar.
  • Correlação por msgID: use o msgID para parear comando e resposta ao analisar o log.

Troubleshooting​

O arquivo de log não é gerado​

Possíveis causas:

  • Plugin não instalado ou serviços não reiniciados após a instalação.
  • Nenhuma mensagem de template facial foi trocada desde a ativação.
  • Processo assíncrono do ACCELERO não está em execução.

Solução:

  1. Confirme com a IONGRADE que o plugin está instalado e que os serviços foram reiniciados.
  2. Reproduza um cadastro ou remoção de template facial para gerar tráfego.
  3. Verifique se o subsistema de processamento assíncrono do ACCELERO está ativo.

Comandos aparecem no log, mas sem resposta correspondente​

Possíveis causas:

  • O gateway facial não respondeu ao comando.
  • Falha de comunicação MQTT entre o gateway e o ACCELERO.

Solução:

  1. Localize o msgID do evento Command sem Response correspondente.
  2. Verifique a conectividade e o estado do gateway facial.
  3. Encaminhe os msgID afetados ao suporte IONGRADE.

Integração com outros módulos​

O plugin observa as mensagens trocadas com os dispositivos de reconhecimento facial vinculados aos controladores. Ele não altera o fluxo de cadastro/remoção de templates — apenas o registra para diagnóstico. Cada comando é associado a uma pessoa pelo campo pesID, permitindo rastrear o envio de templates de um cadastro específico.

A lógica de negócio que dispara a remoção de templates faciais está descrita em Baixa de templates faciais.

Próximos Passos​