01. DADOS GERAIS

02. SITUAÇÃO/REQUISITO

O TOTVS PDV Omni utilizava o serviço Microsoft Visual Studio App Center, especificamente seus recursos de Análise (Analytics) e Diagnóstico (Diagnostics), para a coleta e análise de dados cruciais, como o registro de crashes (erros não tratados) e o monitoramento geral da estabilidade da aplicação.

No entanto, a Microsoft anunciou oficialmente a desativação progressiva (retirement) do Visual Studio App Center. Conforme comunicado em sua documentação oficial (referência: App Center retirement - Visual Studio App Center | Microsoft Learn), os recursos de Análise e Diagnóstico, essenciais para nossa operação, terão seu suporte encerrado após 30 de junho de 2026.

A descontinuação programada destes recursos específicos do App Center representa um risco direto à nossa capacidade de monitorar eficazmente o TOTVS PDV Omni, diagnosticar falhas e garantir a qualidade da aplicação. A dependência de um serviço externo com data definida para encerramento torna mandatória a implementação de uma solução alternativa, robusta e controlada internamente.

Diante deste cenário, tornou-se necessário substituir as funcionalidades de Análise e Diagnóstico providas pelo App Center. O requisito foi desenvolver um novo mecanismo que não apenas replicasse a capacidade essencial de capturar crashes, mas que também aprimorasse o processo, buscando:

• Centralização Abrangente: Coletar não apenas crashes, mas diversos tipos de logs (informativos, avisos, erros) em um único repositório.
• Análise Avançada: Oferecer maior flexibilidade e poder nas consultas, filtros e visualização dos dados coletados.
• Rastreabilidade Integrada: Permitir a correlação de eventos entre o PDV e os serviços de backend (APIs) através de identificadores como o CorrelationId, facilitando o diagnóstico ponta-a-ponta.
• Visualização Clara e Interativa: Disponibilizar dashboards que facilitem a compreensão do estado da aplicação por diferentes perfis (técnico, produto, cliente).
• Autonomia e Sustentabilidade: Garantir o controle sobre a ferramenta de monitoramento e reduzir a dependência de serviços de terceiros.

03. SOLUÇÃO

Para atender aos requisitos e mitigar os riscos associados à desativação do App Center, foi desenvolvida e implementada uma nova solução de monitoramento e logging para o TOTVS PDV Omni. A solução é composta por dois elementos principais:

1. Biblioteca LogCentralizado: Uma nova biblioteca integrada diretamente ao código do TOTVS PDV Omni. Sua responsabilidade é capturar informações de execução, incluindo logs detalhados e exceções não tratadas (crashes), e enviá-las de forma padronizada para uma plataforma central de logs.
2. Dashboard Grafana: Uma interface de visualização web, construída na plataforma Grafana, que se conecta à plataforma central de logs. Este dashboard apresenta os dados coletados pelo LogCentralizado de forma organizada, através de gráficos, tabelas e indicadores, permitindo a análise interativa e o monitoramento em tempo real.

Essa combinação substitui o uso anterior do Microsoft App Center para fins de diagnóstico e análise, oferecendo uma ferramenta mais poderosa, integrada ao ecossistema TOTVS e com maior capacidade de evolução e personalização.

04. INTRODUÇÃO À NOVA SOLUÇÃO

Com o objetivo de aprimorar o monitoramento, diagnóstico e análise de comportamento do TOTVS PDV Omni, a solução LogCentralizado e o Dashboard Grafana oferecem uma visão completa, integrada e com ferramentas de análise mais poderosas, beneficiando tanto equipes técnicas quanto gestores e clientes na compreensão da saúde da aplicação.

Benefícios Principais:

• Visão Centralizada: Todos os logs (informativos, avisos, erros) e crashes do PDV Omni são enviados para um único local.

• Monitoramento em Tempo Real: Acompanhe o comportamento da aplicação e identifique problemas rapidamente.

• Análise Aprofundada: Utilize filtros e visualizações para entender padrões, causas raízes de erros e performance.

• Rastreabilidade: Siga o fluxo de uma operação específica desde o PDV até os serviços de backend.

• Diagnóstico Facilitado: Ferramentas que agilizam a identificação e correção de falhas.

Biblioteca LogCentralizado

A biblioteca LogCentralizado agora faz parte do TOTVS PDV Omni. Sua principal função é coletar informações relevantes sobre a execução da aplicação e enviá-las para a plataforma central de logs.

Captura Automática de Exceções Não Tratadas (Crashes)

Uma funcionalidade crucial, mantida em relação ao que o App Center oferecia, é a captura automática de exceções não tratadas. Isso significa que, se ocorrer um erro inesperado no PDV Omni que não foi previsto e tratado por um bloco try-catch no código, o LogCentralizado irá registrar e enviar automaticamente os detalhes completos desse erro (conhecido como crash ou unhandled exception).

Isso é vital para a estabilidade do sistema, pois garante que mesmo as falhas mais inesperadas sejam registradas, permitindo que a equipe de desenvolvimento as identifique e corrija rapidamente, mesmo que o usuário final não reporte o problema explicitamente.

Dashboard Grafana: Visualizando os Dados

O Dashboard Grafana é a interface visual onde todos os dados coletados pelo LogCentralizado são apresentados de forma organizada e interativa. Ele permite explorar os logs, identificar tendências e investigar incidentes.

Visão de exemplo do dashboard Grafana

Visão Geral do Dashboard:

O dashboard é composto por vários painéis que fornecem diferentes perspectivas sobre os dados:

1. Filtros Principais (Topo): Permitem refinar os dados exibidos em todo o dashboard. Falaremos mais sobre eles abaixo.

2. Indicadores Chave (KPIs): Mostram números importantes, como total de registros, quantidade de PDVs enviando logs, etc. (Ex: "Registros totais por dispositivo", "Versão PDV").

3. Gráficos de Resumo:

   • Crashes Comuns (Gráfico de Pizza): Mostra a distribuição dos tipos de crashes mais frequentes, ajudando a identificar os pontos mais críticos de falha.

   • Classe x Método (Gráfico de Barras): Detalha onde os crashes estão ocorrendo, mostrando a contagem por combinação de classe e método no código.

4. Listagem de Crashes:

   • Crashes Condensados: Apresenta uma lista resumida das mensagens de erro mais recentes ou frequentes, agrupando ocorrências semelhantes.

   • Tabela "Crashes": Exibe uma lista detalhada de cada evento de crash individual, com informações como timestamp, mensagem, tipo de exceção, método, versão do PDV, CorrelationId, etc.

5. Logs Completos: Um painel que mostra o fluxo bruto de todos os logs (não apenas erros) recebidos, útil para análises mais detalhadas de sequências de eventos.

Utilizando os Filtros do Dashboard

Filtros gerais da parte superior do dashboard

Os filtros na parte superior do dashboard são ferramentas poderosas para isolar informações específicas:

• Sistema Operacional: Filtra logs originados de um sistema operacional específico (ex: Windows ou Android).

• Ambiente: Seleciona o ambiente de execução (ex: Development, Staging, Production). Essencial para separar dados de teste dos dados reais de operação.

• Código Loja: Filtra logs de um ou mais códigos de loja específicos. Útil para investigar problemas reportados por uma loja em particular.

• Versão PDV: Isola logs de uma versão específica do TOTVS PDV Omni. Importante para analisar o comportamento de uma nova versão ou comparar com versões anteriores.

• EventType (Tipo de Evento): Este filtro é especialmente útil para agrupar mensagens de log que representam o mesmo tipo de ocorrência, mesmo que os detalhes específicos variem.

  • Como funciona (Explicação Simplificada): Imagine que o sistema gera logs como "Usuário 'joao' falhou ao logar" e "Usuário 'maria' falhou ao logar". Embora os nomes de usuário sejam diferentes, a estrutura ou modelo da mensagem é a mesma ("Usuário '...' falhou ao logar"). O EventType é um identificador único gerado automaticamente para esse modelo de mensagem.

  • Benefício: Ao filtrar por um EventType específico (selecionando-o na lista ou clicando em um valor na tabela de logs), você pode rapidamente ver quantas vezes um determinado tipo de evento (como falha de login, erro ao salvar venda, etc.) ocorreu, independentemente dos detalhes variáveis (como nome de usuário, código do produto, etc.). Isso ajuda a identificar padrões e problemas recorrentes de forma muito mais eficiente do que lendo logs individuais.

• CorrelationId (ID de Correlação): Este é um identificador único que conecta uma série de eventos relacionados, geralmente iniciados por uma ação do usuário no PDV e que podem envolver chamadas a serviços externos (APIs).

  • Como funciona: Quando o usuário realiza uma ação significativa no PDV (ex: clica no botão "Finalizar Venda", "Consultar Produto"), um CorrelationId único pode ser gerado. Esse mesmo ID é então incluído em todos os logs gerados no PDV referentes a essa ação e também é enviado junto com as chamadas para as APIs de backend. As APIs, por sua vez, incluem esse mesmo CorrelationId em seus próprios logs relacionados àquela requisição.

  • Benefício: Se um cliente reporta um problema com uma operação específica (ex: uma venda que não foi concluída), e você consegue obter o CorrelationId associado a essa tentativa (seja por um log de erro no PDV ou outro meio), você pode usar esse ID para filtrar todos os logs (do PDV e do backend) relacionados àquela única transação. Isso fornece uma visão completa e sequencial de tudo o que aconteceu durante aquela operação específica, do clique inicial no PDV até o processamento final no servidor, tornando o diagnóstico de problemas complexos muito mais rápido e preciso. É como ter o "fio da meada" para rastrear uma operação do início ao fim através de diferentes sistemas.

Conclusão

A combinação da biblioteca LogCentralizado e do Dashboard Grafana oferece uma solução robusta e moderna para o monitoramento do TOTVS PDV Omni, substituindo e aprimorando as capacidades anteriormente oferecidas pelo App Center. Ela fornece ferramentas essenciais de análise e rastreabilidade que capacitam as equipes a entender melhor o sistema, identificar problemas proativamente e garantir uma melhor experiência para o usuário final. A capacidade de filtrar por EventType e CorrelationId são diferenciais chave para diagnósticos eficientes em ambientes distribuídos.