Debugging e troubleshooting¶
Para instalar o ecossistema com credenciais locais, Keycloak e mocks, siga Instalação completa local.
Comece distinguindo quatro situações: processo não iniciou, aplicação não ficou pronta, dependência não está acessível ou operação retornou erro. Um health UP não comprova todo o fluxo de negócio.
Java e Go no host¶
No BFF, o README documenta depuração Quarkus com porta explícita:
./mvnw.cmd quarkus:dev -Ddebug=5006
Conecte o debugger da IDE à porta configurada e confira a mensagem de inicialização. Expor uma porta Docker, isoladamente, não habilita um agente de debug JVM. Este comando do BFF não foi executado nesta jornada.
Para Go, go run não habilita debugger nem hot reload. Não há uma configuração única de Delve comprovada para todos os serviços; use os testes e logs existentes até definir uma configuração específica para o serviço/IDE.
Containers¶
Durante a etapa Docker do primeiro deploy:
docker logs gateway-docs-jsonhandler
docker inspect gateway-docs-jsonhandler --format '{{.State.Status}}'
Confira porta publicada, variável de contexto HTTP, arquitetura da imagem e arquivos copiados. Falta de target/quarkus-app deve ser corrigida no empacotamento, não com alterações improvisadas no Dockerfile.
Cluster local¶
Para a release de exercício:
kubectl --context kind-totvs-gateway -n gateway-docs-first-deploy get pods -o wide
kubectl --context kind-totvs-gateway -n gateway-docs-first-deploy describe deployment totvs-gateway-json-handler
kubectl --context kind-totvs-gateway -n gateway-docs-first-deploy get events --sort-by=.metadata.creationTimestamp
kubectl --context kind-totvs-gateway -n gateway-docs-first-deploy logs deployment/totvs-gateway-json-handler --tail=100
helm status gateway-docs-jsonhandler --kube-context kind-totvs-gateway --namespace gateway-docs-first-deploy
| Sintoma | Conferência inicial |
|---|---|
Pending |
Eventos, recursos solicitados, label apptype=service e anti-affinity do chart |
ErrImageNeverPull |
Tag exata e carregamento em todos os nós elegíveis do cluster correto |
ImagePullBackOff |
Imagem/política renderizadas e acesso ao registry; veja imagens locais |
| Falha de probe | Porta, caminho e logs; não aumente tolerâncias para esconder URL errada |
| HTTP 404 | Raiz HTTP e caminho do endpoint; JSON Handler usa /jsonhandler/api/json-schema/generate |
| HTTP 400 | Tipo e serialização do payload; no exemplo, input contém uma string JSON |
| Port-forward desconectado | Rollout pode encerrar o Pod selecionado; reinicie o encaminhamento |
| Health UP, operação falha | Teste o endpoint funcional e suas dependências; UP não valida contratos downstream |
No BFF, a raiz HTTP é /, mas quarkus.http.non-application-root-path=/gateway/q define o caminho de health. Use /gateway/q/health/ready; a raiz das APIs e a raiz dos endpoints de gerenciamento são configurações distintas.
Investigar além do serviço¶
Use Dependências e integrações para encontrar consumidores e destinos, dados para ownership/cache e métricas locais para observabilidade. As análises arquiteturais registram riscos conhecidos, sem substituir o diagnóstico da requisição concreta.
Infraestrutura corporativa é documentada pelo TOTVS Apps; comandos Kind e Helm deste portal são procedimentos locais.
Referências no código
Para conectar uma IDE à JVM de um Pod, siga Debug remoto Java no Kind, que utiliza global.devMode dos charts existentes.