26 out 2026 · linux, diagnostico · 5 min

Como usar journalctl para achar o erro do sistema

O journalctl filtra o journal do systemd por unidade, prioridade, janela de tempo e boot. Com três filtros em sequência, uma falha que sumiu no meio de mil linhas aparece em 3 linhas. Não precisa instalar nada: o journal já está lá.

O systemd grava stdout, stderr e mensagens de cada unidade num journal binário indexado, e o journalctl é a ferramenta que lê esse índice. O erro não some porque o log rotacionou cedo demais; some porque ninguém filtrou. A sequência abaixo reduz milhares de linhas a um punhado, e cada filtro é cumulativo, ou seja, pode ser removido se cortar demais.

A sequência que uso

Comece pela unidade, porque é o filtro que mais corta. Se o serviço se chama demo-journalctl-test2.service, o comando é journalctl --user -u demo-journalctl-test2 --no-pager. O --no-pager evita o less que truncava a saída. Se o serviço é do sistema, tire o --user e rode com sudo ou esteja num grupo que leia o journal do sistema.

Depois refine pela prioridade. As prioridades do syslog, do 0 ao 7, são emerg, alert, crit, err, warning, notice, info e debug. Para achar erro, -p err já basta; para caça mais ampla, -p warning inclui o err. O journalctl colore por nível quando a saída é um terminal: vermelho para err e acima, amarelo para warning.

Em seguida, a janela de tempo. --since "10 minutes ago" e --until "5 minutes ago" delimitam o incidente. Datas absolutas também funcionam, no formato 2026-10-26 07:00:00. Quem sabe o horário aproximado economiza minutos de leitura.

O último filtro é o boot. journalctl -b 0 mostra o boot atual, -b -1 o anterior, e --list-boots lista os boots conhecidos. Um serviço que falha só depois de reiniciar aparece no boot certo, não no atual. Combine com -u e você isola o problema.

Para procurar um texto específico no log, use -g com uma expressão regular: journalctl -u meu-servico -g "timeout|refused|exit-code". É mais rápido do que jogar a saída no grep, e respeita os filtros anteriores.

O artefato

#!/usr/bin/env bash
# journalctl-filtros.sh - roda a sequência de filtros num serviço.
# Uso: ./journalctl-filtros.sh [unidade] [prioridade] [janela]
set -euo pipefail

UNIDADE="${1:-demo-journalctl-test2.service}"
PRIORIDADE="${2:-err}"
JANELA="${3:-10 minutes ago}"

if command -v journalctl >/dev/null 2>&1; then
    echo "== por unidade =="
    journalctl --user -u "$UNIDADE" --no-pager -o short | tail -n 20
    echo "== por prioridade =="
    journalctl --user -p "$PRIORIDADE" -n 5 --no-pager
    echo "== por janela =="
    journalctl --user --since "$JANELA" -u "$UNIDADE" --no-pager -o short
    echo "== por boot atual =="
    journalctl --user -b 0 -u "$UNIDADE" --no-pager -o short | tail -n 5
    echo "== texto no log =="
    journalctl --user -u "$UNIDADE" --no-pager -g "falha|FAILURE|exit-code" | tail -n 5
else
    # modo demonstração: mesmo raciocínio sobre um log de exemplo
    LOG=/tmp/journal-demo.log
    printf '%s\n' \
        "Oct 26 07:01:36 host systemd[992]: Started demo-journalctl-test2.service - demo falha com erro." \
        "Oct 26 07:01:36 host joseti[3256587]: falha de demonstracao do journalctl" \
        "Oct 26 07:01:36 host systemd[992]: demo-journalctl-test2.service: Main process exited, code=exited, status=1/FAILURE" \
        "Oct 26 07:01:36 host systemd[992]: demo-journalctl-test2.service: Failed with result 'exit-code'." > "$LOG"
    echo "== por unidade =="
    grep "$UNIDADE" "$LOG"
    echo "== por prioridade (err) =="
    grep -i "falha\|FAILURE\|exit-code" "$LOG"
    echo "== por janela (ultimas 3) =="
    tail -n 3 "$LOG"
    echo "== texto no log =="
    grep -E "falha|FAILURE|exit-code" "$LOG"
fi

Os comandos avulsos, para colar um por vez:

journalctl --user -u demo-journalctl-test2 --no-pager
journalctl --user -p err -n 5 --no-pager
journalctl --user --since "10 minutes ago" -u demo-journalctl-test2 --no-pager
journalctl --user -b 0 -u demo-journalctl-test2 --no-pager
journalctl --user -u demo-journalctl-test2 --no-pager -g "falha|FAILURE"

Como verificar

Rode o filtro por prioridade e confira a saída esperada:

$ journalctl --user -p err -n 3 --no-pager
Oct 26 07:01:22 host sudo[3256262]: joseti : a password is required ; PWD=/home/joseti/sites ; USER=root ; COMMAND=/usr/bin/true
Oct 26 07:01:36 host joseti[3256587]: falha de demonstracao do journalctl
Oct 26 07:01:38 host joseti[3256639]: teste logger direto

São 3 linhas. Se aparecerem mais, o filtro de prioridade não foi aplicado; se aparecerem menos, a janela ou a unidade cortou demais.

Se der errado

• -- Logs begin at ... e nenhuma linha: a unidade está com outro nome. Confira com systemctl status ou systemctl --user --failed. O sufixo .service pode ser omitido no -u, mas o nome base não.
• Permission denied ou No journal files were found: o usuário não lê o journal do sistema. Entre no grupo systemd-journal ou adm, ou use sudo journalctl. Para o journal do próprio usuário, use --user.
• O journal some após reiniciar a máquina: o armazenamento é volátil. Edite /etc/systemd/journald.conf, defina Storage=persistent, e reinicie o systemd-journald. Depois disso o journal sobrevive ao reboot.
• A saída vem cortada no meio: o pager paginou. Use --no-pager ou defina SYSTEMD_PAGER= vazio. Para copiar para um arquivo, redirecione com > saida.txt.

Prioridades em uma tabela

Comece em err. Se não achar, desça para warning e depois info. Subir para crit só quando o serviço caiu de vez.

FAQ

O journalctl substitui o /var/log? Em sistemas com systemd, sim para a maioria dos serviços. Alguns programas ainda escrevem em /var/log diretamente. Os dois convivem; o journalctl não lê arquivo de texto.

Como ver o log em tempo real? Use journalctl -f, equivalente ao tail -f. Combine com -u para seguir um serviço: journalctl -f -u meu-servico.

Por que minha mensagem com logger não aparece? O logger envia para o syslog, que o journald captura. Se a prioridade for baixa, filtre com -p debug ou remova o filtro. Mensagens de usuário aparecem no journal do usuário com --user.

Posso exportar o journal para análise? Sim. journalctl -o json ou journalctl -o export produzem formatos processáveis. Para um intervalo, combine com --since e --until e redirecione para um arquivo.

O -g aceita regex completo? Aceita expressões regulares estendidas, como alternância com |. Caracteres especiais precisam de aspas. Use -g depois dos outros filtros, porque a busca textual é a mais lenta.

Veja também Cron do jeito certo: ambiente, log e o que não roda para o caso em que o log some porque o cron não redirecionou a saída. Container sem root mostra como manter o serviço enxuto para o log não virar ruído.