Seu app parou. Encontre a primeira pista útil.

Defina uma falha observável

“Parou” pode significar um erro HTTP, um timeout, uma tarefa que não terminou ou um processo que saiu. Anote uma URL ou ação, seu último horário de funcionamento conhecido, o primeiro horário de falha e seu fuso horário. Inclua se todos são afetados ou apenas um cliente. Mantenha a sessão SSH atual aberta durante a investigação; alterar regras de acesso não é uma primeira resposta necessária a um erro de aplicação.

Este guia assume um host Linux usando systemd, um serviço de aplicação chamado first-api.service, e um endpoint de saúde local em 127.0.0.1:3000/healthz. Esses padrões correspondem ao primeiro guia de implantação de API. Substitua pelos seus nomes reais. A inspeção pode exigir permissão de administrador para ver processos ou logs de outros usuários. Os comandos e saídas abaixo são ilustrativos; nenhuma instância de provedor foi testada para este guia.

Mantenha anotações fora do diretório do próprio app com falha. Registre observações antes de interpretações: “conexão recusada em 09:18 UTC” é um fato; “o VPS precisa de mais CPU” ainda é uma hipótese. Se o próprio servidor estiver inacessível, use seu acesso de recuperação estabelecido e colete detalhes da conexão em vez de assumir que um reinício do app é possível.

Leia o estado do processo e seu histórico recente

systemctl status first-api.service --no-pager --full
systemctl show first-api.service -p ActiveState -p SubState -p Result -p ExecMainStatus -p NRestarts

A visualização de status descreve a invocação atual ou mais recente e inclui mensagens recentes do journal. As propriedades selecionadas fornecem um registro compacto para comparar depois. Um estado de falha ou uma contagem de reinicializações crescente merece investigação; um processo ativo ainda precisa de um teste de requisição. Essas são verificações diferentes, como descrito na referência upstream do systemctl.

Se a unidade estiver ausente, primeiro verifique seu nome e o método de implantação. Um aplicativo iniciado em um terminal interativo, um contêiner e um serviço systemd têm proprietários e logs diferentes. Criar um novo serviço imediatamente pode deixar duas cópias competindo pela mesma porta. Identifique a configuração existente antes de alterá-la.

Verifique o listener e faça uma requisição local

sudo ss -ltnp
curl --silent --show-error --max-time 5 http://127.0.0.1:3000/healthz

Procure o endereço e a porta esperados, depois identifique o processo proprietário. Um processo escutando em outra porta pode estar saudável, mas inacessível pelo proxy configurado. Um processo diferente pode ter reivindicado a porta esperada. O manual do ss define as opções de listener e processo.

Se a requisição local funcionar e a requisição pública HTTPS falhar, continue pelas verificações de DNS, TLS e proxy. Se o listener estiver ausente, examine a falha de inicialização. Se a conexão for bem-sucedida, mas o aplicativo retornar um erro, investigue essa rota e suas dependências. Curl sem --fail pode ser concluído com sucesso para uma resposta de erro HTTP, então leia a resposta em vez de confiar apenas no código de saída. Veja opções de resposta e falha do curl.

Leia em torno da primeira falha, não apenas a última linha

sudo journalctl -u first-api.service --since "30 minutes ago" --no-pager -n 100
sudo journalctl -k --since "30 minutes ago" --no-pager -n 100

A primeira consulta seleciona o serviço; a segunda seleciona mensagens do kernel. Ajuste o intervalo para incluir a última requisição bem-sucedida e a mudança que precedeu a indisponibilidade. Acesso e retenção determinam o que permanece disponível. A referência upstream do journalctl explica filtros de unidade, tempo e kernel. Redija tokens, dados de clientes e strings de conexão antes de compartilhar trechos.

Trecho ilustrativo de um aplicativo separado com recurso de upload:

09:18:03 field-api: opening upload directory
09:18:03 field-api: EACCES: permission denied, open '/var/lib/field-api/uploads/index.json'
09:18:03 field-api: startup aborted

Isso aponta para o acesso do usuário do serviço a um caminho específico. Verifique a propriedade do arquivo e do diretório pai em relação às instruções de release. Não conceda acesso amplo de escrita a todo o sistema de arquivos. Uma mensagem posterior do proxy “upstream unavailable” seria uma consequência neste cenário, então reparar o proxy primeiro perderia a causa.

Compare recursos com o release mais recente

free -h
df -h / /opt/first-api
df -i / /opt/first-api

Esses snapshots ajudam a perguntar se pressão de memória, espaço no sistema de arquivos ou esgotamento de inodes coincidiram com a falha. A interpretação deles pertence ao guia de memória e disco; uma única leitura ocupada não estabelece a causa. Um serviço também pode atingir seu próprio limite de recursos enquanto o restante do host tem capacidade.

Compare o identificador da release implantada, o comando de inicialização, os nomes das variáveis de ambiente necessárias e os caminhos de dados com a última release funcional. Não despeje valores secretos de ambiente em um relatório. Procure por um diretório renomeado, dependência de runtime ausente, mudança de porta ou migração de banco de dados incompatível. Declare o que mudou e o que o erro prevê que você deve encontrar.

Faça uma correção justificada e verifique a recuperação

Escolha a menor correção sustentada pelas evidências. Para a falha de permissão ilustrativa, isso significa restaurar o acesso pretendido para a conta de serviço e, em seguida, fazer uma tentativa de inicialização controlada. Se você usar uma release de código comprovadamente funcional, primeiro estabeleça se o esquema do banco de dados dela permanece compatível. Um rollback de código não pode reverter automaticamente uma migração de dados.

Após a correção, repita as mesmas verificações de serviço, endpoint local e requisição pública. Confirme que uma ação representativa do aplicativo funciona, que novos erros pararam e que o processo permanece estável durante a próxima carga de trabalho normal. Políticas de reinicialização podem ajudar a recuperar um processo, mas não tornam saudável um programa persistentemente quebrado; consulte a referência do serviço systemd para a política real.

Finalize sua nota de incidente com o sintoma, a primeira pista útil, a mudança feita e o resultado da verificação. Se a causa permanecer incerta, relate essa incerteza com evidências redigidas em vez de rotular uma reinicialização temporária como correção permanente. Melhore a checklist de release com a verificação que teria detectado essa falha mais cedo.