Protheus: rotina parou? O que ch…

Protheus: rotina parou? O que checar

Atualizar o Protheus é um procedimento rotineiro em ambientes corporativos, mas nem sempre a entrega do build ou patch é indolor: rotinas que funcionavam passam a falhar. Este artigo técnico detalha um checklist aprofundado para diagnosticar e remediar rotinas interrompidas após atualização. Assumo familiaridade com arquitetura Protheus (AppServer, SmartClient, AdvPL/TDS), administração de sistemas e bases de dados corporativas.

1. Primeiras verificações e isolamento do problema

Ao detectar uma rotina parada após atualização, o primeiro objetivo é reduzir a superfície de análise. Proceda assim:

• Confirmar escopo: a falha ocorre para todos os usuários/empresas ou apenas em um tenant/filial? Reproduzindo em homologação ou somente em produção?
• Reproduzir o erro com dados mínimos: capture parâmetros de entrada, sequência de telas ou endpoint que dispara a rotina.
• Registrar o momento exato da atualização e identificar quais builds/patches foram aplicados (número do build do executável AppServer/SmartClient, build do dicionário, patches aplicados).
• Se possível, validar se houve rollback parcial (arquivos substituídos apenas no servidor de aplicação, sem tocar a base de dados).

2. Logs: onde procurar e como interpretar

Logs são a principal fonte de evidência. Conheça os pontos de coleta e os padrões de erro relevantes.

• AppServer: examine o arquivo de log do AppServer (appserver.log ou arquivo configurado). Procure por ERROR, FATAL, EXCEPTION, SIGSEGV, undefined symbol, ou mensagens de compilação de runtime.
• SmartClient: logs locais do SmartClient (trace/totvsclient.log) podem revelar erros de interface, scripts ou problemas de comunicação com o AppServer.
• Banco de dados: logs do SGBD (SQL Server Error Log, alert.log do Oracle, syslog/journalctl para Postgres) para problemas de conexão, deadlocks ou erros de execução de SQL gerado pela rotina.
• Sistema operacional: syslog, journalctl (Linux) e Event Viewer (Windows) ajudam a identificar falhas de bibliotecas nativas, permissões ou ações de antivirus que interromperam processos.
• Ferramentas de busca: utilize tail -f, grep/egrep, ou utilitários de log central (ELK, Splunk) com queries por timestamps, nome do usuário e termos de exceção.

3. Compatibilidade de versões e notas de breaking changes

Atualizações frequentemente trazem mudanças de API, remoção de parâmetros ou alteração de comportamento de funções internas. Verifique:

• Matriz de compatibilidade: confirme a compatibilidade entre versão do AppServer, SmartClient, dicionário de dados e build do ADVPL. Consulte notas técnicas da TOTVS relativas ao build aplicado.
• Notas de release e breaking changes: procure por alterações em funções ADVPL, assinatura de APIs, mudanças em parâmetros de compilador ou no comportamento de rotinas de sistema.
• Patches incrementais: algumas correções são entregues em hotfixes subsequentes; valide se há hotfixes correlacionados com o problema.
• Versões de bibliotecas nativas: alteração em bibliotecas C/C++ (DLL/.so) que o AppServer consome — verifique se houve atualização de runtime (glibc, OpenSSL, etc.).

4. Ambiente de execução: serviços, variáveis e bibliotecas

Depois de confirmar que a versão aplicada é suportada, verifique o ambiente onde o Protheus roda.

• Serviços: reinicie AppServer, SmartClient e quaisquer serviços auxiliares (job servers, brokers). Em Linux, use systemctl restart e confire status com systemctl status.
• Variáveis de ambiente: PATH, LD_LIBRARY_PATH (Linux) ou PATH (Windows) podem apontar para versões antigas de bibliotecas. Verifique variáveis customizadas utilizadas pelo AppServer.
• Permissões de arquivos: após update, permissões de execuçã o ou propriedade de arquivos executáveis ou bibliotecas podem ter sido alteradas. Confirme usuário que executa o AppServer tem leitura/execução nos binários e acesso ao diretório do dicionário.
• Arquivos de configuração: appserver.ini, smartclient.ini, server.ini ou arquivos equivalentes podem ter parâmetros novos ou descontinuados. Compare com a versão padrão distribuída no build.
• Consistência entre servidores: em ambientes com multi-appserver, certifique-se que todos tenham o mesmo build e configuração; divergências causam comportamento imprevisível.

5. Código customizado: recompilação e incompatibilidades AdvPL

Customizações são a causa mais comum de rotinas que “pararam” após update. Pontos-chave:

• Recompilação obrigatória: após atualização do dicionário ou do compilador ADVPL, módulos custom (RPOs ou fontes advpl) normalmente precisam ser recompilados com o novo ambiente. Falta de recompilação gera erros de symbols não encontrados ou comportamento incorreto.
• Deprecated APIs: funções internas podem ter sido alteradas ou removidas. Procure substitutos na documentação e atualize includes.
• Includes e bibliotecas: verifique paths de include e libs compartilhadas. Imports de bibliotecas custom ou de terceiros podem falhar se as bibliotecas do novo build mudaram suas interfaces.
• Controle de versão do código: sempre mantenha fontes em repositório e registre o commit/versão implantada. Isso facilita rollback seletivo em caso de incompatibilidade.
• Testes unitários e de integração: rotinas isoladas podem passar, mas falhar em combinação. Invista em uma suíte mínima de testes que valide fluxos críticos após recompilação.

6. Banco de dados: scripts de atualização, schema e performance

Atualizações podem incluir scripts que alteram schema, índices ou procedimentos armazenados. As consequências variam:

• Scripts aplicados com erro: verifique histórico de migração e log de execução dos scripts. Um script parcialmente aplicado (com erros) pode deixar o schema inconsistente.
• Campos e índices ausentes: rotinas que dependem de colunas adicionadas podem falhar com erro de column not found. Faça um diff entre schema esperado e o atual.
• Permissões: a conta de conexão (usuário do Protheus no SGBD) pode necessitar de privilégios novos para executar comandos DDL/DDL temporário ou criar objetos temporários.
• Performance e planos de execução: alterações em índices ou estatísticas do SGBD podem gerar planos diferentes e trazer timeouts. Recoleta de estatísticas (UPDATE STATISTICS / ANALYZE) e reconstrução de índices podem ser necessárias.
• Conectores/Drivers: mudanças no driver ODBC/JDBC ou atualização do cliente do SGBD podem romper compatibilidade. Confirme versão e parâmetros de timeout/charset.

7. Integrações externas, webservices e segurança (TLS/Certificados)

Erros em rotinas que consomem serviços externos frequentemente estão ligados a mudanças de segurança ou protocolos:

• TLS e ciphers: atualizações podem forçar TLS 1.2/1.3. Clients que utilizam bibliotecas antigas (OpenSSL/SSPI) podem falhar na handshake. Verifique logs de handshake e atualize bibliotecas ou configure ciphers compatíveis.
• Alteração de endpoints ou autenticação: provedores de serviço podem alterar URLs ou métodos de autenticação (Basic → OAuth2). Verifique payloads e headers usados pela rotina.
• Certificados: certs expirados ou cadeia incompleta no servidor impedem conexões seguras. Valide a cadeia, a data e a confiança do certificado usado pelo AppServer.
• Timeouts e retry policies: mudanças de latência em rede após atualização (por exemplo, novas validações síncronas) podem fazer rotinas exceder thresholds. Ajuste timeouts e implemente retry com backoff quando apropriado.

8. Ferramentas de diagnóstico avançado

Quando a causa não é óbvia, use técnicas de diagnóstico para criar evidências determinísticas:

• Ativar trace detalhado do AppServer/SmartClient: aumente loglevel temporariamente e capture dados de entrada/saída. Atenção ao volume de logs e dados sensíveis.
• Debug remoto com TDS: se a rotina for ADVPL, anexe um depurador (breakpoints) para inspecionar variáveis e fluxo de execução.
• Comparação binária e de configuração: use tools de diff para comparar diretórios antes/depois (rsync --dry-run, diff -r). Identifique arquivos alterados inadvertidamente.
• Captura de tráfego: se a rotina envolve chamadas HTTP/HTTPS, capture via tcpdump ou Wireshark para inspecionar headers, ciphers e payloads (filtrar por IP/porta).
• Profiling de performance: monitore CPU, memória, I/O e locks durante execução da rotina. Tools como top, vmstat, iostat, perf (Linux) ou Performance Monitor (Windows) ajudam a identificar gargalos.
• Ambiente de replicação: crie um ambiente de homologação que reproduza a configuração de produção (mesmos builds, dados amostrados) para testar hipóteses sem risco.

9. Estratégias de mitigação e rollback

Quando uma rotina parada impacta operação, medidas rápidas são necessárias:

• Mitigação temporária: isole o impacto (bloquear job scheduler, redirecionar usuários, scripts alternativos) enquanto investiga.
• Rollback controlado: execute rollback apenas se tiver garantia de restauração consistente (backup do dicionário, binários e dump da base). Rollback parcial pode deixar sistema inconsistente.
• Hotfix local: se a causa for um módulo custom, substitua o módulo problemático por versão recompilada/ajustada para o novo build, validando em homologação antes de promoção.
• Comunicação: informe stakeholders sobre impacto, plano de ação e janela de manutenção. Documente passos de rollback e pré-requisitos.

10. Checklist pós-correção e prevenção para futuras atualizações

Com o problema resolvido, implemente controles para reduzir recorrência:

• Automatizar testes: criar suítes automatizadas (smoke tests e testes de integração) que rodem após cada build ou patch.
• Plano de release e validação: checklist formal que inclui recompilação de fontes custom, validação de scripts de DB, testes de integração e verificação de logs nativos.
• Ambientes pareados: manter ambientes de homologação que reproduzam configurações de produção, incluindo versões de SGBD, sistemas operacionais e conectores.
• Documentação de customizações: inventário de módulos custom, dependências externas e ponto de contato; associá-los a riscos de versão.
• Monitoramento proativo: definir métricas e alertas (erros de aplicação, aumentos súbitos de latência, falhas de handshake TLS) para detectar regressões logo após deploy.

11. Exemplo prático: fluxo rápido de diagnóstico

Exemplo condensado de sequência de ações operacionais para quando uma rotina crítica falha após update:

• 1) Isolar: parar o job/fluxo que dispara a rotina para evitar dados inconsistentes.
• 2) Coletar logs: extrair appserver.log, smartclient.log e logs do SGBD com timestamp do erro.
• 3) Verificar mensagem de erro: buscar por “undefined symbol”, “column not found”, “connection refused”, “TLS handshake” — keywords orientam a causa.
• 4) Verificar build: confirmar números de build do AppServer e SmartClient e checar notas de versão.
• 5) Recompilar fontes custom: fazer build em ambiente controlado e validar se erro persiste.
• 6) Testar conexão e scripts do DB: executar manualmente SQL gerado pela rotina e validar esquema/permissões.
• 7) Mitigar e/ou rollback: se identificação imediata, aplicar hotfix; se não, considerar rollback planejado.

12. Contato com suporte e documentação

Se esgotadas verificações internas, reúna evidências antes de abrir chamado com a TOTVS/support:

• Coletar pacotes de logs, dump de tela, versã o completa de componentes (executáveis, libs, SGBD), arquivo de configuração e passos para reproduzir.
• Incluir amostras de entradas e quick-fix tentados (recompilação, restart, rollback parcial).
• Priorizar severidade e impacto de negócio para acelerar atendimento.

Conclusão: rotinas que deixam de funcionar após atualizar o Protheus raramente são "misteriosas" — a causa normalmente pertence a uma das frentes: incompatibilidade de versão, ambiente de execução alterado, código custom que precisa ser recompilado ou mudanças no banco/integradores. Seguir uma investigação ordenada (reprodução, logs, comparação de builds, recompilação, validação de DB, tracing de integrações) acelera a resolução e reduz a necessidade de rollback.