0004 — Logs Logback + Bugsink (protocolo Sentry)¶
Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-08-11 · Decidido em: 2026-04-01
Contexto¶
O processamento é assíncrono (o cliente recebe 202 e o trabalho pesado corre em thread do pool). Falhas de parse/persistência acontecem fora do ciclo request/response, então precisam de destinos além do console: um agregador para alertas e correlação entre deploys, e uma trilha por-processamento que o suporte consulta na UI.
Decisão¶
Logback com CONSOLE (stdout) + appender Sentry (8.16.0) que envia os
eventos para o Bugsink (bug.xadm.biz), que fala o protocolo Sentry. O
log operacional do servidor vai para stdout (o Coolify captura) — norma da
casa (engenharia/java-micronaut): servidor não grava log-de-framework em arquivo;
só CLI/worker o faz. A trilha por-processamento (app.logs.dir, default
logs/execucoes/processamento-<id>.log, exibida na UI) é artefato de domínio,
não log de framework, e segue em arquivo. Falhas de processamento ficam com
status=ERRO em xls_processamento e viram evento no Bugsink.
Consequências¶
- Erro assíncrono não some: fica no stdout capturado, na trilha por-processamento,
na tabela (
status=ERRO) e no Bugsink. - Log do servidor centralizado pelo runtime (Coolify), sem arquivo de framework a rotacionar/mapear em volume; um destino a menos para dar errado.
- Correlação cross-deploy e alertas ficam no Bugsink, sem operar um Sentry próprio (Bugsink é self-hosted, compatível com o SDK Sentry).
- Alinhado ao irmão
bi-transporte-xls— mesma stack de erro entre os apps BI.
Alternativas consideradas¶
- Só log em arquivo: sem alerta e sem visão agregada entre instâncias/deploys. Descartado.
- Sentry SaaS: custo e dado saindo da infra da casa; o Bugsink self-hosted cobre o caso pelo mesmo protocolo. Descartado.