Evlog CLI: como medir a observabilidade do seu app antes da produção

Seu aplicativo pode estar funcionando perfeitamente hoje e ainda assim deixar a equipe completamente no escuro amanhã.

O pagamento falha, um webhook para de processar, o login retorna erro para parte dos usuários. O sistema responde com um código HTTP, mas não explica qual etapa falhou, qual cliente foi afetado nem o que fazer em seguida. É nesse intervalo entre “o app quebrou” e “agora sabemos por quê” que a observabilidade deixa de ser detalhe técnico e vira uma decisão de negócio.

O Evlog CLI propõe uma pergunta simples: se a produção quebrar esta noite, quais partes do seu aplicativo conseguiriam explicar o que aconteceu?

Para responder com algo além de teoria, executamos o evlog map no portal da Escola de Aplicativos, um projeto Nuxt real. O resultado foi 35 de 100. Encontramos rotas bem instrumentadas, áreas sem contexto de negócio e alertas que exigem julgamento humano. Este artigo mostra o que o número significa, como começar sem paralisar o time e onde a ferramenta ainda não alcança.

O que é o Evlog CLI?

O Evlog CLI é uma ferramenta de análise estática para observabilidade. Ele lê o código-fonte do projeto, identifica pontos de entrada importantes e verifica se cada fluxo registra contexto suficiente para ajudar em uma investigação.

Ele não precisa ser publicado junto com a aplicação. O pacote @evlog/cli roda na máquina do desenvolvedor ou no CI, separado do runtime evlog. Atualmente, a documentação lista suporte a Nuxt, Nitro, Next.js com App Router e TanStack Start.

O comando principal é:

pnpm dlx @evlog/cli@0.3.0 map

Pense nele como uma revisão automática do que o seu app seria capaz de contar sobre si mesmo. Enquanto um linter procura problemas de sintaxe e um teste verifica comportamento esperado, o evlog map procura rotas que podem falhar sem deixar uma explicação útil.

Ele analisa, entre outros pontos:

• handlers de API;
• páginas que buscam dados;
• middlewares;
• tarefas em segundo plano;
• rotas sensíveis, como autenticação e pagamento;
• tratamento de erros e blocos catch.

O resultado inclui um score geral e a classificação de cada ponto como instrumentado, parcial, escuro ou isento.

O teste em um portal Nuxt real

Rodamos o Evlog CLI 0.3.0 na aplicação pública da Escola:

pnpm dlx @evlog/cli@0.3.0 map \
  --cwd apps/portal \
  --no-write \
  --json

O mapa encontrou 80 pontos de entrada:

O número assusta à primeira vista, principalmente porque o portal já usa Evlog no runtime, envia eventos para o Axiom e possui enriquecimento de contexto. Isso revelou a primeira lição importante: ter uma plataforma de logs instalada não significa que cada fluxo registra informação útil para o negócio.

Em uma integração Nuxt, um evento genérico pode carregar método, caminho e status da resposta. Isso ajuda a saber que /api/auth/... retornou erro, mas pode não explicar:

• qual operação de autenticação estava acontecendo;
• em que etapa ela parou;
• se o erro veio do provedor, do banco ou da validação;
• qual ação a equipe deve tomar;
• se houve risco de segurança ou impacto financeiro.

O CLI chama esse tipo de handler de “vazio” quando o código não adiciona contexto próprio. A rota não está necessariamente silenciosa em produção, mas o evento pode ser pouco útil para descobrir a causa.

O que a ferramenta encontrou

Uma das rotas destacadas foi o handler de autenticação. Por ser uma área sensível, o CLI procurou contexto, erro estruturado, auditoria e tratamento explícito de exceções.

Alguns alertas faziam sentido imediatamente. Uma operação crítica precisa dizer mais do que “falhou”. Um evento útil poderia incluir o tipo de fluxo, o provedor, o estágio alcançado e um motivo seguro:

const log = useLogger()

log.set({
  flow: 'social-login',
  provider: 'google',
  stage: 'callback',
})

try {
  await completeAuthentication()
}
catch (error) {
  throw createError({
    statusCode: 502,
    statusMessage: 'Não foi possível concluir o login',
    data: {
      why: 'O provedor de identidade não respondeu como esperado',
      fix: 'Tente novamente e verifique a integração se o erro persistir',
    },
  })
}

O objetivo não é registrar senha, token, e-mail ou conteúdo sensível. É oferecer contexto operacional seguro para que a equipe diferencie um problema temporário de provedor, uma regra de validação e uma falha interna.

Outros alertas precisavam de interpretação. O projeto possui blocos catch que ignoram falhas em rastreamento secundário para nunca interromper o login. Há também respostas 404 intencionais, usadas para não revelar a existência de determinadas rotas administrativas.

“Corrigir” esses pontos automaticamente poderia piorar o produto. Nesses casos, a decisão correta pode ser manter o comportamento e documentar a exceção, desabilitando a regra naquele trecho com uma justificativa.

Essa é a segunda lição: o mapa inicia uma revisão; ele não substitui a revisão.

As seis perguntas por trás do score

O score atual considera seis requisitos principais. Eles podem ser traduzidos para perguntas que qualquer pessoa responsável pelo produto consegue avaliar:

1. Existe um evento completo?

O fluxo cria um evento amplo, capaz de reunir o que ocorreu durante toda a requisição, em vez de espalhar frases desconectadas por vários logs?

2. O evento recebe contexto de negócio?

O código adiciona informações como operação, etapa, entidade e resultado? “POST retornou 500” é técnico. “Criação da assinatura falhou na autorização do pagamento” orienta uma investigação.

3. Erros explicam causa e próximo passo?

Uma mensagem útil responde o que aconteceu, por que pode ter acontecido e o que deve ser verificado. Isso reduz o tempo entre o alerta e a ação.

4. Operações sensíveis deixam auditoria?

Login, mudança de permissão, reembolso e alteração de dados críticos merecem um registro de auditoria. Esse registro não deve conter segredos, mas precisa mostrar qual ação ocorreu e seu resultado.

5. Exceções são tratadas de forma consciente?

Um catch vazio pode esconder um problema. Se a falha for deliberadamente ignorada, a razão precisa estar clara. Se afetar a operação principal, deve enriquecer o evento e retornar um erro coerente.

6. A interface consegue explicar falhas de busca?

Não basta observar apenas o servidor. Uma página que busca dados precisa oferecer estado de erro, possibilidade de nova tentativa e contexto suficiente para correlacionar a experiência do usuário com o backend.

map, doctor e init: qual comando usar?

O CLI possui responsabilidades diferentes, e misturá-las cria expectativas erradas.

evlog map: descubra as lacunas

Use para mapear a cobertura e priorizar o trabalho. O modo JSON permite guardar o resultado como artefato do CI ou alimentar um painel. --no-write garante que a análise não altere arquivos.

Em um monorepo, analise um app por vez:

evlog map --cwd apps/portal --no-write
evlog map --cwd apps/gestor --no-write

Isso também evita um score agregado que mistura aplicações com riscos e públicos diferentes.

evlog doctor: confira a instalação

O doctor verifica se a integração está configurada corretamente. Ele é útil depois da instalação, de uma atualização ou quando os eventos deixaram de chegar ao destino esperado.

evlog init: configure com segurança

O init prepara a integração, detecta o projeto e mostra o plano antes de tocar nos arquivos. A documentação informa que ele evita sobrescrever código existente e apresenta etapas manuais quando não consegue fazer uma alteração com segurança.

Antes de aceitar qualquer mudança:

evlog init --dry-run

Para quem trabalha com vibe coding ou agentes, essa prévia é especialmente valiosa. O agente pode propor a configuração, mas a equipe ainda enxerga quais arquivos serão modificados.

evlog map --baseline .evlog-baseline.json

evlog map --min-score 35

- name: Verificar observabilidade
  run: pnpm dlx @evlog/cli@0.3.0 map --cwd apps/portal --min-score 35 --no-write