Tutorial do Debian 13 / Diagnosticar falhas de serviços, falta de memória e erros de espaço em disco

Falhas de serviço no Debian 13 podem ser isoladas verificando separadamente a causa da finalização do processo, as portas e respostas reais, e o status da memória e do sistema de arquivos. As medidas diferem em casos como código de saída 42, finalização por falta de memória (OOM) devido a limites de memória, e quando o processo está ativo mas retorna HTTP 503 devido à falta de espaço. Este tutorial reproduz as três situações sob limites de recursos pequenos, registra as evidências e, em seguida, remove a causa.

Capturar evidências antes de reiniciar

Primeiro, determine o horário do problema, a solicitação que falhou e o caminho de destino. Se você reiniciar incondicionalmente, os sintomas podem desaparecer temporariamente, mas a causa pode permanecer e você pode perder o status de término e as informações de recursos. Substitua o seguinte nginx.service pelo nome real do serviço a ser investigado.

date --iso-8601=seconds
sudo systemctl status nginx.service --no-pager
sudo systemctl show nginx.service -p ActiveState -p SubState -p Result -p ExecMainCode -p ExecMainStatus -p MainPID
sudo journalctl -b -u nginx.service -n 80 --no-pager
ss -ltn
free -h
vmstat -y 1 3
df -hT /
df -i /

status ou is-active podem retornar um código de saída diferente de zero em um estado de falha. No script de coleta, crie uma ramificação para registrar esse estado e não pule verificações posteriores incondicionalmente. Como os logs podem conter endereços, contas e informações de solicitações, restrinja os caminhos de armazenamento e o escopo de compartilhamento.

Observação Verificações adicionais Declarações a evitar
serviço falhou Result, código de saída, sinal e log recente Nem todas as falhas são devido à falta de memória.
Ativo, mas falha na solicitação Listener, status HTTP e leituras/escritas de dados Ativo não significa que a funcionalidade do usuário está normal.
A memória parece estar baixa Memória disponível, alterações de swap, limites de serviço e evidências de OOM OOM não deve ser diagnosticado apenas pelo valor da coluna free.
Falha na escrita Montagem, bloco, inode e permissão do caminho que falhou Não apenas verifique o espaço livre do disco raiz e termine.

Preparar o ambiente isolado e o programa completo

Um grupo de controle (cgroup) agrupa processos para controle de recursos. tmpfs é um sistema de arquivos baseado em memória com um limite de tamanho configurável separadamente. Instale as ferramentas ausentes com sudo apt install python3 curl procps. Pare se lfstudent estiver ausente, a porta 8080 estiver ocupada ou qualquer verificação de pré-requisito falhar; o protetor de colisão encerra seu shell, então use um shell de laboratório dedicado.

É requerida uma VM dedicada Debian 13 com sudo, Python 3, curl e o controlador de memória do cgroup v2. A VM de verificação tinha cerca de 4GiB de memória, mas a prática foi conduzida apenas dentro de um limite de 64MiB para um único serviço e um novo tmpfs de 4MiB. Isso não esgota os serviços operacionais reais nem o disco root.

Este é um exemplo de um ambiente com um usuário regular lfstudent. Para outras contas, adapte as diretivas User e Group e os identificadores numéricos de usuário (UID) e grupo (GID) proprietários do tmpfs. Primeiro, verifique se o nome e a porta estão vazios.

id lfstudent
stat -fc %T /sys/fs/cgroup
cat /sys/fs/cgroup/cgroup.controllers
ss -ltn
for p in /usr/local/libexec/lf-diag31.py /etc/systemd/system/lf-diag31.service /mnt/lf-diag31 /var/backups/lf-debian13-31; do
    if test -e "$p"; then echo "Already exists: $p" >&2; exit 1; fi
done
sudo install -d -m 755 /usr/local/libexec
sudo install -d -m 700 /var/backups/lf-debian13-31

O sistema de arquivos deve ser cgroup2fs, e a lista de controladores deve incluir memory. O programa completo a seguir está dividido nos modos exit42, oom e serve. O modo oom aloca no máximo 128MiB de payload de bytearray, além da sobrecarga do interpretador, e deve ser executado com o comando subsequente de limite de cgroup. GET no serve é uma solicitação de confirmação experimental que escreve 4KiB no caminho isolado e não é usada como exemplo de implementação de aplicação web geral.

sudo tee /usr/local/libexec/lf-diag31.py > /dev/null <<'PY'
import os,sys
from http.server import BaseHTTPRequestHandler,HTTPServer
mode=sys.argv[1]
if mode=='exit42':
    print('intentional exit code 42',flush=True)
    raise SystemExit(42)
if mode=='oom':
    chunks=[]
    for i in range(8):
        chunks.append(bytearray(16*1024*1024))
        print(f'allocated_chunks={i+1}',flush=True)
    raise SystemExit('Expected cgroup memory limit')
if mode!='serve': raise SystemExit('Unknown mode')
class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        try:
            with open('/mnt/lf-diag31/probe.bin','ab') as f:
                f.write(b'.'*4096)
                f.flush()
                os.fsync(f.fileno())
            status=200;body=b'write probe ok\n'
        except OSError as e:
            print(f'write probe errno={e.errno}: {e.strerror}',flush=True)
            status=503;body=b'write probe failed\n'
        self.send_response(status)
        self.send_header('Content-Type','text/plain')
        self.send_header('Content-Length',str(len(body)))
        self.end_headers();self.wfile.write(body)
HTTPServer(('127.0.0.1',8080),Handler).serve_forever()
PY
sudo chmod 644 /usr/local/libexec/lf-diag31.py

Distinguir códigos de saída de encerramentos por OOM

O primeiro teste retorna intencionalmente o código de saída 42. Como --wait propaga esse resultado, é esperada uma falha no comando. Use um shell de laboratório interativo sem saída automática em caso de falha para esses comandos systemd-run que falham deliberadamente, ou capture explicitamente seu status diferente de zero antes de continuar para as consultas de diagnóstico.

sudo systemd-run --unit=lf-exit31 --wait --property=User=lfstudent --property=RuntimeMaxSec=10s /usr/bin/python3 /usr/local/libexec/lf-diag31.py exit42
sudo systemctl show lf-exit31.service -p Result -p ExecMainCode -p ExecMainStatus
sudo journalctl -b -u lf-exit31.service --no-pager

O resultado real foi Result=exit-code, ExecMainCode=1, ExecMainStatus=42. O 1 em ExecMainCode é o código do método de terminação e não significa que o programa terminou com 1. Leia a indicação code=exited exibida por status juntamente com o status de saída real 42.

Em seguida, para um único serviço, especificamos MemoryMax=64M, MemorySwapMax=0 e um limite de execução de 10 segundos. O limite é aplicado apenas a uma unidade transitória dedicada, sem afetar outros trabalhos da conta. Pare se esses limites não puderem ser aplicados; nunca execute o modo oom fora de sua unidade delimitada.

sudo systemd-run --unit=lf-oom31 --wait --property=User=lfstudent --property=MemoryMax=64M --property=MemorySwapMax=0 --property=RuntimeMaxSec=10s --property=OOMPolicy=stop /usr/bin/python3 /usr/local/libexec/lf-diag31.py oom
sudo systemctl show lf-oom31.service -p Result -p ExecMainCode -p ExecMainStatus -p MemoryMax -p MemorySwapMax -p MemoryPeak
sudo journalctl -b -u lf-oom31.service --no-pager

OOM (Out of Memory) refere-se a uma situação em que a memória não pode ser alocada. cgroup é um recurso do kernel que aplica limites de recursos a grupos de processos. Mesmo que o host tenha memória livre, o processo pode ser encerrado devido ao limite do cgroup. Na verificação, foram observados Result=oom-kill, ExecMainCode=2, ExecMainStatus=9 e MemoryMax e MemoryPeak=67.108.864 bytes, MemorySwapMax=0.

Você não pode concluir que houve OOM apenas com o sinal 9. Uma parada forçada pelo administrador também poderia gerar o mesmo sinal, então analisamos Result junto com o diário daquele momento. Também investigamos a intervenção do kernel ou do systemd-oomd dependendo da situação. O significado dos limites por serviço pode ser encontrado em descrição de controle de recursos do systemd, e a hierarquia e os eventos de memória podem ser verificados na documentação do Linux cgroup v2.

Não altere imediatamente o limite para ilimitado. Ajuste-o após verificar os requisitos normais de carga de trabalho, vazamentos, trabalhos simultâneos e o orçamento geral do host. Remover o limite é diferente de resolver a causa raiz.

Diagnosticar um serviço em execução que não consegue gravar

Crie um tmpfs separado de 4MiB e serviço de loopback. O UID/GID do lfstudent da VM de verificação era 1000, e abaixo obtemos os valores reais usando id. Você deveria ter verificado anteriormente se o caminho existente e a porta 8080 estão livres.

sudo mkdir /mnt/lf-diag31
sudo mount -t tmpfs -o "size=4M,nr_inodes=64,uid=$(id -u lfstudent),gid=$(id -g lfstudent),mode=0700,nosuid,nodev" tmpfs /mnt/lf-diag31
findmnt --mountpoint /mnt/lf-diag31
sudo tee /etc/systemd/system/lf-diag31.service > /dev/null <<'UNIT'
[Unit]
Description=LF bounded write failure HTTP lab 31
[Service]
Type=exec
User=lfstudent
Group=lfstudent
ExecStart=/usr/bin/python3 /usr/local/libexec/lf-diag31.py serve
UNIT
sudo systemctl daemon-reload
sudo systemctl start lf-diag31.service
curl --noproxy '*' -fsS http://127.0.0.1:8080/

A resposta normal é write probe ok. Se as requisições falharem imediatamente após o início, verifique o status e os logs e tente novamente depois de um tempo. Confirme a resposta de referência bem-sucedida antes de prosseguir para o próximo passo.

Abaixo, como lfstudent, tentamos escrever 1MiB até 8 vezes. O ponto de montagem de 4MiB enche primeiro, causando ENOSPC (sem espaço restante no dispositivo). Não execute se você não puder verificar a montagem desse tmpfs.

sudo -u lfstudent python3 - <<'PY'
import errno,pathlib
p=pathlib.Path('/mnt/lf-diag31/fill.bin')
try:
    with p.open('xb') as f:
        for i in range(8):
            f.write(b'x'*1048576);f.flush()
except OSError as e:
    if e.errno!=errno.ENOSPC:raise
    print('BOUNDED_TMPFS_ENOSPC')
else:raise SystemExit('Expected bounded ENOSPC')
PY
curl --noproxy '*' -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/
sudo systemctl is-active lf-diag31.service
ss -ltn | grep '127.0.0.1:8080'
findmnt --target /mnt/lf-diag31 -o TARGET,SOURCE,FSTYPE,OPTIONS
df -hT /mnt/lf-diag31
df -i /mnt/lf-diag31
sudo journalctl -b -u lf-diag31.service -n 20 --no-pager

Na realidade, o HTTP retornou 503, mas o serviço estava ativo e a porta estava em LISTEN. Os blocos do tmpfs ocuparam todos os 4MiB disponíveis, e apenas 3 de 64 inodes foram usados. As falhas de escrita estavam ligadas ao erro errno=28 registrado no journal: No space left on device. A causa não foi a inatividade do serviço ou esgotamento de inodes, mas sim o esgotamento dos blocos no tmpfs dedicado.

Agora, remova apenas o arquivo de preenchimento de laboratório conhecido e faça a mesma solicitação ao serviço novamente. Não reinicie o serviço.

sudo rm -- /mnt/lf-diag31/fill.bin
curl --noproxy '*' -fsS http://127.0.0.1:8080/
df -hT /mnt/lf-diag31

Na verificação, a resposta voltou a ser write probe ok. Nas operações, a limpeza é realizada apenas quando o alvo que pode ser deletado está claro. Logs regulares ou dados não são excluídos indiscriminadamente; avaliamos o produtor, retenção, rotação e planos de expansão. Se for um erro de permissão ou montagem somente leitura, liberar espaço não resolverá o problema, então o diagnóstico deve seguir a mensagem de erro.

Interpretar métricas de memória e E/S dentro do período de amostragem

No comando free, free informa a memória não utilizada, enquanto available estima a memória que novos aplicativos poderiam usar sem fazer swap. A memória em cache não é necessariamente desperdiçada. O manual do free explica como cada coluna é calculada.

free -h
vmstat -y 1 3
ps -eo pid,comm,rss,%mem,%cpu --sort=-rss | head

O relatório inicial padrão do vmstat pode incluir médias desde a inicialização, então o omitimos com -y e observamos três vezes em intervalos de 1 segundo. si e so representam entrada/saída de swap, r indica tarefas executáveis, e b aponta para tarefas bloqueadas aguardando a conclusão de I/O, fornecendo pistas. Não é possível determinar falha de disco ou gargalo de CPU a partir de uma única amostra de valores de wa ou CPU. Verifique o intervalo de amostragem no manual do vmstat e compare-o com o momento do incidente.

Após verificação, esta VM tinha aproximadamente 3,4 GiB disponíveis e 0 de uso de swap, mas essa observação não representa a memória disponível nem a capacidade de serviço em outros momentos. Nos relatórios, separamos valores observados, julgamentos apoiados por esses valores e suposições não verificadas.

Preservar evidências, confirmar a recuperação e limpar o exercício

Preserve as evidências antes de limpar o estado de falha. reset-failed limpa o indicador de falha, mas não corrige problemas de memória ou de arquivo.

sudo journalctl -b -u lf-oom31.service --no-pager | sudo tee /var/backups/lf-debian13-31/oom-journal.txt > /dev/null
sudo journalctl -b -u lf-diag31.service --no-pager | sudo tee /var/backups/lf-debian13-31/write-failure-journal.txt > /dev/null
sudo systemctl show lf-oom31.service -p Result -p ExecMainCode -p ExecMainStatus -p MemoryMax -p MemoryPeak | sudo tee /var/backups/lf-debian13-31/oom-state.txt

O código de saída 42 indica uma terminação intencional do programa, oom-kill significa terminação relacionada aos limites reais de memória do serviço, e 503 foi uma falha de escrita durante o estado ativo. No último caso, a nova requisição HTTP teve sucesso após a liberação de espaço, confirmando a recuperação da gravação sem reiniciar o serviço.

sudo systemctl stop lf-diag31.service
sudo rm -- /mnt/lf-diag31/probe.bin
sudo umount /mnt/lf-diag31
sudo rmdir /mnt/lf-diag31
sudo rm -- /usr/local/libexec/lf-diag31.py /etc/systemd/system/lf-diag31.service
sudo systemctl daemon-reload
sudo systemctl reset-failed lf-exit31.service lf-oom31.service
sudo systemctl --failed --no-pager

Na verificação, serviços dedicados, pontos de montagem e arquivos foram removidos, e a lista de serviços com falha estava vazia. Em incidentes reais, finalizamos coletando evidências, tomando ações apropriadas à causa, confirmando respostas e dados, e registrando o alcance da observação. Não consideramos a funcionalidade do usuário e os dados como recuperados apenas porque o processo foi reiniciado.