Investigar um problema

Investigar é ir do sintoma à causa sem adivinhar pelo caminho. O Radar está desenhado para esse percurso: escolhe-se o que falhou, vê-se cada execução uma a uma, e segue-se para trás até ao passo que a originou.

Esta página percorre esse caminho em quatro etapas — a API, a sessão, o problema, e o registo de auditoria que explica porquê agora.

#Uma API que falha

1. Abre a app e vai a Radar.
2. Na secção APIs e scripts, clica na linha da API — por exemplo oportunidades.
3. Abre-se um separador com o nome dela, e no topo três etiquetas: o nome interno, 116 chamadas e média 4ms. Quando há falhas, aparece também "N falhas (X%)".

A tabela tem uma linha por chamada — nunca agrupada — com cinco colunas:

Coluna	O que mostra
Quando	O momento da chamada.
Estado	O estado HTTP devolvido.
Operação	A operação pedida, quando a chamada a identifica.
Resultado	sem erro, ou o tipo de erro que rebentou.
Tempo	Quanto demorou.

A barra Filtrar… por cima da tabela reduz a lista por qualquer um destes campos: só as falhas, só as acima de 500 ms, só as de hoje. A paginação em baixo diz onde estás — 1–50 de 116.

#O detalhe de uma chamada

Clica numa linha e abre-se o painel de detalhe, em baixo, com três separadores:

Separador	O que traz
Geral	Quando, Tempo, Estado, Origem, Quem fez a chamada e o Trace que a identifica.
Enviado	O que a chamada levou. Quando há dúvidas de tipos, mostra campo a campo o Enviado e o Tipo esperado, com o suspeito a vermelho.
Resposta	O que voltou. Uma chamada que não devolveu nada diz "Não voltou nada."; uma que não levou nada diz "Esta chamada não levou nada."

Os scripts têm um painel gémeo: uma linha por execução, com o Código de saída, a Origem do disparo e a Consola — a saída que o script escreveu. Um script sem execuções no período diz "Sem execuções registadas."

#A linha do tempo de uma sessão

Uma chamada isolada raramente explica um erro. A pergunta seguinte é sempre "o que é que a pessoa estava a fazer?" — e é para isso que servem as sessões.

1. Em Radar, expande a secção Sessões.
2. Clica na visita que te interessa — 23:11 · demo.
3. O painel abre com quem entrou, quando, e um resumo: 15 passos em 5 páginas.

A tabela é a linha do tempo da visita, um passo por linha:

Coluna	O que mostra
Nome	O passo: uma página, um ecrã, um evento, uma chamada a uma API, uma leitura de dados.
Estado	Se correu bem ou mal.
Origem	De onde veio o passo — Páginas, Ecrãs, Acções, Dados.
Tempo	Quanto demorou.
Cascata	A barra que mostra quando aconteceu dentro da sessão e quanto ocupou.

A cascata é o que torna a leitura imediata: as barras alinham-se no tempo, e um passo que demorou vê-se sem ler número nenhum. Clica numa linha para o detalhe — com Página, Quando, Tempo e Desde o início da sessão (+0.0s, +2.4s, …). Um passo que não chamou o servidor di-lo: "Este passo não chamou o servidor."

#Um erro de código

Os erros que nasceram no código dos eventos aparecem na secção Ecrãs, agrupados pela causa: um problema por erro distinto, com o número de ocorrências ao lado.

Clica num para abrir o painel do problema, que junta tudo o que se sabe sobre ele:

Zona	O que responde
Código	O excerto do teu código, com a linha culpada destacada, e a Posição exacta.
Caminho até aqui	O que a pessoa fez antes de rebentar — página, ecrã, leituras de dados, o clique final.
Rasto do erro	O rasto técnico, quando foi guardado.
Fluxo	O percurso do erro pelas peças da app.
Abrir no designer	Leva-te directo ao evento onde o erro nasceu.

O botão Abrir no designer é o fim natural da investigação: encontraste a linha, agora vais corrigi-la.

Um erro que a plataforma classificou como Da plataforma mostra outra coisa: "Este erro nasceu no runtime do Keplin, não no código da tua app. Não há nada a corrigir do teu lado — vale a pena reportá-lo." — com uma Referência para copiar.

#Os problemas, em todas as apps

O menu Observabilidade → Problemas é a mesma matéria, junta e com estado. Cada linha é um problema agrupado, com Ocorrências, Utilizadores afectados, Visto pela primeira vez e Visto pela última vez.

Uma instalação sadia tem esta página vazia — "Nenhum problema corresponde aos filtros", com Limpar filtros para alargar a pesquisa. Antes de concluir que não há problemas, confirma o período no topo: com 1h escolhido, um erro de ontem não aparece.

Cada problema tem três estados, e mudam-se no próprio painel:

Acção	O que faz
Resolver	Marca-o como tratado — "Problema marcado como resolvido." Se voltar a acontecer, reabre-se sozinho.
Ignorar	Tira-o do caminho sem o resolver — "Problema ignorado." Para o ruído que se conhece.
Reabrir	Devolve-o a aberto — "Problema reaberto."

Dentro de um problema, a Cadeia do problema desenha o percurso: o contexto no browser, as execuções correlacionadas, o erro e o impacto observado. Quando não há como ligar as peças, di-lo em vez de inventar — "As ligações tracejadas representam apenas contexto confirmado, não uma relação causal inferida."

#Os eventos, um a um

Observabilidade → Eventos é a lista crua: uma linha por execução de API, script ou sistema, incluindo as que correram bem.

Colunas: Quando, Tipo, App, O quê, Duração e Resultado. Os filtros do topo cortam por App, Tipo, Estado, Severidade e período; Limpar filtros repõe tudo.

Clica numa linha e o detalhe abre ao lado, com Resumo e Dados — e Abrir a página completa quando precisas de mais espaço. As mensagens de erro aparecem na língua original do servidor, de propósito: traduzi-las afastava-as do texto que se procura na documentação.

#E porquê agora? A auditoria

Um erro que começou hoje quase sempre tem uma alteração por trás. Observabilidade → Auditoria guarda as alterações administrativas e de configuração — criar, alterar, apagar, executar, importar, exportar, revogar, repor password, alterar role — com quem as fez, em que app e quando.

Clica numa linha e o detalhe mostra o Antes e o Depois da alteração. É a resposta directa à pergunta que fecha a maior parte das investigações: "o que é que mudou ontem à tarde?"

#O caminho, resumido

1. Visão geral — que app está a arder.
2. Radar da app — que API, script ou ecrã.
3. O painel dele — que chamada, com que dados, em que momento.
4. A sessão — o que a pessoa fez antes.
5. O problema — a linha de código e o botão Abrir no designer.
6. A Auditoria — o que mudou para isto começar.

#Porque não vejo…?

• …o detalhe de uma chamada? Nenhuma linha está seleccionada. A tabela diz "Escolhe uma linha para ver o detalhe."
• …as ocorrências de um problema antigo? Podem ter sido levadas pela rotação de registos — o painel avisa quando isso acontece.
• …o Caminho até aqui preenchido? Nem todas as ocorrências trazem o percurso; quando não trazem, o painel diz "Sem caminho registado para esta ocorrência." em vez de mostrar passos inventados.
• …o botão Abrir no designer? Só aparece em erros com origem no código da app. Os erros da plataforma não têm nada para abrir.