Guia de Troubleshooting: Metodologia Técnica para Homologação de Ambientes

Resumo: Este guia estabelece o workflow técnico e as melhores práticas para identificação de causa raiz durante processos de homologação, atualizações ou falhas após migrações de ambientes na Now Platform.

1. Introdução: O Princípio da Clareza

Antes de iniciar qualquer análise técnica (logs ou scripts), o time de suporte deve garantir que a “pergunta técnica” está correta. O erro mais comum no troubleshooting de homologação é tentar corrigir algo que não foi bem definido.

Checklist de Definição (wwww):

O que (what): Qual é o comportamento esperado vs. o comportamento atual?
Onde (where): Ocorre em todos os registros ou em um específico? (Ex: Apenas no portal ou no backend?)
Quem (who): Afeta todos os usuários ou apenas usuários com roles específicas?
Quando (when): Começou após um clone, uma atualização de Store App ou uma mudança de configuração manual?

Princípios de Definição:

A Pergunta Correta: O que o cliente está tentando realizar e o que exatamente está falhando?
Frequência e Escopo: O erro é consistente (acontece sempre) ou intermitente? Afeta um usuário específico, uma role ou a instância inteira?
O Gatilho: Qual foi a última alteração no ambiente? (Ex: Clone de PROD para DEV, instalação de patch ou alteração de System Property).

Estrutura de Reporte de Análise (Padrão S.T.E.P.)

Para acelerar a comunicação entre níveis (N1 para N3), toda análise de homologação deve ser reportada seguindo:

S (Status): O impacto atual no negócio.
T (Trigger): O que dispara o erro.
E (Evidence): Logs anexados e códigos de erro específicos.
P (Payload): Exemplo de dados (Sys_id) usados no teste.

A Correlação entre Metodologias:

O QUE? → Corresponde ao S (Status) e T (Trigger)
No S.T.E.P.: O Status define o impacto (o que parou) e o Trigger define a ação (o que foi feito para o erro aparecer).
Exemplo: “O botão de aprovação sumiu (Status) após o utilizador clicar em ‘Guardar’ (Trigger).”

2. ONDE? → Corresponde ao P (Payload) e T (Trigger)

No S.T.E.P.: O Payload indica o Sys_id e a tabela (onde o dado está). O Trigger indica o local funcional (Portal, Workspace ou Backend).
Exemplo: “Ocorre na tabela u_request_final (Payload) dentro do Service Portal (Trigger)."

3. QUEM? → Corresponde ao P (Payload) e S (Status)

No S.T.E.P.: No Status/Payload incluímos se o impacto é apenas para utilizadores com a role itil ou se é geral.
Exemplo: “Apenas utilizadores com a role ‘approver_user’ (Payload) visualizam o erro de ‘Access Denied’ (Status).”

4.QUANDO? → Corresponde ao T (Trigger) e E (Evidence)

No S.T.E.P.: A Evidência traz o timestamp dos logs (o momento exato). O Trigger traz o evento que disparou a falha.
Exemplo: “O erro foi registado às 14:22 (Evidence) imediatamente após o submetimento do formulário (Trigger).”

2. Workflow de Investigação Técnica

Para uma análise eficaz, o suporte deve seguir esta hierarquia de ferramentas:

A. Análise de Logs (O “Rastro” do Sistema)

Sempre verifique os Log Files antes de tentar reproduzir o erro.

System Logs -> Errors/Warnings: Procure por erros de “Scope”, “Access Denied” ou “Null Pointer Exception” que ocorreram no exato momento do teste de homologação.

Transaction Logs: Verifique o tempo de resposta. Se o ambiente de homologação está lento, o Transaction Log dirá se o gargalo é no SQL, no Browser ou no Processamento de Rede.

B. Debugging de Sessão (O Cenário Real)

Utilize as ferramentas de Session Debug para isolar o problema sem afetar outros usuários:

Debug Security: Essencial para homologação. Verifica se uma ACL (Access Control) nova está bloqueando a visualização de campos após a migração.

Debug Business Rules: Identifica qual script de servidor alterou um valor inesperadamente durante a homologação.

C. Scripts Server-Side e Client-Side

Se o erro for funcional (um botão não funciona ou um cálculo está errado):

Server-Side: Use o Script Debugger para percorrer o código linha a linha. Coloque breakpoints em Business Rules ou Script Includes suspeitas.
Client-Side: Utilize o JavaScript Log and Field Watcher para entender se o erro está no navegador do usuário (Client Scripts ou UI Policies).

D. Deleted Records

D. Auditoria de Registros Excluídos (Deleted Records)

Nem sempre o problema é o que foi alterado, mas sim o que deixou de existir. Em ambientes de homologação, é comum que registros de configuração sejam excluídos acidentalmente.

System Deleted Records: Se um comportamento que funcionava parou subitamente, verifique a tabela de sys_metadata_delete. Ela rastreia componentes de aplicação (como campos, tabelas ou scripts) que foram removidos.
Undelete: O Salva-vidas: A ServiceNow permite restaurar registros excluídos através do módulo “Deleted Records”. Se um registro de dados (como um usuário de teste ou um grupo de aprovação) sumiu durante a homologação, você pode recuperá-lo com todos os seus relacionamentos originais.
Filtro de Auditoria: Use o histórico de auditoria (sys_audit) para identificar quem excluiu e quando, cruzando essa informação com o seu Checklist de Clareza.

E. Node Log File Download (A Caixa-Preta do Servidor)

Quando os logs convencionais não apresentam erros, mas o comportamento do ambiente de homologação continua instável, é necessário descer ao nível do servidor.

Acesso: System Logs > Utilities > Node Log File Download.
Quando usar: Essencial para investigar falhas de integração (Outbound/Inbound), erros de autenticação (SAML/SSO), ou quando um job agendado (Scheduled Job) simplesmente não inicia.
Diferencial: Diferente do log do sistema, aqui você tem acesso aos logs brutos do Java e da infraestrutura do nó atual, permitindo identificar erros que a interface do ServiceNow pode não capturar.

F. Evidence (Evidências e Diagnóstico de Infraestrutura)

Além dos logs de erro, a evidência definitiva da saúde do ambiente de homologação é extraída diretamente do motor da instância.

Logs e Screenshots: Anexe os erros específicos encontrados nos passos anteriores.
O “Check-up” Final via **stats.do**: Como última e crucial evidência, execute o comando stats.do diretamente no navegador (URL da instância + /stats.do). Ele fornece o "DNA" do ambiente naquele exato momento:
Versão e Build: Confirme se o patch level é exatamente o mesmo entre os ambientes comparados.
Node ID: Identifique em qual nó o erro ocorreu (útil para descartar falhas isoladas de hardware/nó).
Servlet Memory: Verifique se há pressão de memória no ambiente de homologação, o que pode causar comportamentos erráticos em scripts que funcionam em Produção.
Connected Users: Valide a carga do ambiente no momento do teste.

G. XMLStats.do (Análise de Dados Estruturados)

Enquanto o stats.do é visual, o XMLStats.do fornece uma visão detalhada e estruturada da performance do nó.

O que observar: Ele permite uma análise granular do uso de semáforos, transações de banco de dados e estatísticas do agendador (Scheduler).
Uso em Homologação: É a ferramenta ideal para scripts de monitoramento ou para comparar rapidamente dois ambientes em formato de texto estruturado. Ele revela contagens de transações e tempos médios de resposta que ajudam a identificar se o ambiente de homologação está sob estresse incomum.

H. Threads.do (A Visão de Processamento em Tempo Real)

O Threads.do é a ferramenta definitiva para identificar processos travados ou "zumbis".

O que ele faz: Mostra exatamente o que cada “thread” (linha de processamento) do servidor está executando naquele milésimo de segundo.
Diagnóstico de Travamentos: Se a homologação “congelou”, o Threads.do revela qual script ou transação está consumindo todo o processamento do nó. Ele mostra o tempo que cada thread está ativa, permitindo identificar processos de longa duração que estão bloqueando o ambiente.

3. Isolamento da Causa Raiz (A Técnica do “Ponto de Falha”)

Durante a homologação de ambientes, use o método de exclusão:

Desative e Teste: Desative a última customização feita. O erro persiste? Se sim, a falha é nativa ou de uma configuração anterior.
Compare Ambientes: O comportamento em Produção é diferente de Homologação? Use o Compare Environments ou verifique as System Properties (sys_properties) – muitas vezes um ID de integração ou uma propriedade de segurança está diferente entre os ambientes.

4. Documentação da Solução (O Ciclo do Conhecimento)

O troubleshooting só é considerado encerrado quando o aprendizado é compartilhado/documentado para evitar que o problema se repita no próximo ciclo de homologação.

Fato: O que foi encontrado.
Causa Raiz: Por que o erro ocorreu (ex: falha de permissão de Cross-Scope).
Resolução: Passo a passo da correção aplicada.
Documentação Imediata (KCS): Se a solução foi “óbvia” ou “fácil”, ela deve ser um artigo de KB. São as soluções simples que mais consomem tempo do suporte quando não documentadas.
Feedback para Automação: Se um erro foi encontrado manualmente, avalie: “Podemos criar um teste no ATF (Automated Test Framework) para que este erro seja pego automaticamente na próxima vez?”

Referências de Apoio

“A metodologia acima é baseada nas melhores práticas globais de engenharia de suporte. Recentemente, descobri que a própria ServiceNow oferece um treinamento oficial que aprofunda exatamente estes pontos de Debugging e Logs, o que valida que estamos seguindo o caminho padrão ouro da plataforma.”

Créditos da Adaptação Brasileira

Este guia foi complementado por:

Tiago Macul
Com o apoio da Comunidade NowBridge.