# Evlog CLI: como medir a observabilidade do seu app antes da produção
> Testamos o evlog map em um portal Nuxt real: veja como o CLI encontra rotas sem contexto, prioriza correções e protege o CI sem substituir logs e traces.
**Autores:** Mauro Mequelussi
**Publicado:** 2026-08-06T12:00:00.000Z
**Atualizado:** 2026-08-06T12:00:34.557285219Z
**Tags:** nuxt, vibe-coding, logs-estruturados, wide-events, observabilidade, ci-cd, evlog
---
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 é:

```bash
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.

::callout{type="info" title="Score de observabilidade não é monitoramento"}
O CLI examina o código, não o tráfego real. Ele não substitui logs de produção, métricas, traces, alertas nem testes. Seu papel é encontrar lacunas antes que uma falha real dependa delas.
::

## O teste em um portal Nuxt real

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

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

O mapa encontrou 80 pontos de entrada:

| Resultado | Quantidade |
| --- | ---: |
| Instrumentados | 22 |
| Parciais | 0 |
| Escuros | 30 |
| Isentos | 28 |
| Score geral | 35/100 |

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:

```ts
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:

```bash
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:

```bash
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.

::read-more{slug="cloudflare-analytics-engine-observabilidade" label="Entenda como logs, métricas e traces se completam em produção" placement="mid_content"}

## Como levar observabilidade para o CI sem travar a equipe

O caminho mais tentador é exigir 100/100 no primeiro dia. Em um produto existente, isso costuma criar dezenas de correções superficiais, exceções mal justificadas ou uma regra que todos passam a ignorar.

Uma estratégia melhor é usar uma catraca: o projeto pode não estar perfeito hoje, mas não deve piorar amanhã.

### Comece registrando a linha de base

```bash
evlog map --baseline .evlog-baseline.json
```

A linha de base permite detectar regressões por ponto de entrada e por verificação. Isso é melhor do que olhar apenas o total. Uma rota crítica pode perder auditoria enquanto outra rota simples melhora e mantém a mesma média.

### Defina um mínimo alcançável

```bash
evlog map --min-score 35
```

No caso do portal, 35 seria o piso inicial, não a meta final. Depois de corrigir fluxos de maior risco, o time poderia elevar o mínimo gradualmente para 45, 60 e assim por diante.

O comando retorna códigos de saída diferentes para sucesso, falha de verificação e uso incorreto. Isso permite bloquear uma pull request quando a cobertura realmente regredir.

### Fixe a versão no CI

O Evlog CLI ainda é jovem e suas regras estão evoluindo. A própria documentação recomenda fixar a versão. Se o CI usar sempre “latest”, uma atualização de regra pode alterar o score sem qualquer mudança no projeto.

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

Quando atualizar a ferramenta, revise as regras e regenere a linha de base de forma consciente.

## O que corrigir primeiro

Trinta pontos escuros não significam trinta tarefas com a mesma prioridade. Uma boa ordem considera impacto, frequência e dificuldade de diagnóstico.

| Prioridade | Exemplos | Por que começar aqui |
| --- | --- | --- |
| Alta | autenticação, pagamento, webhook, mudança de permissão | falhas geram perda financeira, risco ou bloqueio do usuário |
| Média | criação de conteúdo, upload, automação, busca principal | afetam operação e experiência, mas costumam ter contorno |
| Baixa | endpoints simples, health checks, páginas estáticas | pouco contexto pode ser suficiente |

Para cada rota importante, pergunte:

1. Que decisão alguém tomaria com este evento?
2. Qual informação reduz o tempo de investigação?
3. Que dado jamais deveria aparecer no log?
4. Quando uma falha secundária pode ser ignorada?
5. Quem recebe o alerta e qual é o próximo passo?

Esse processo conecta o score ao produto. Uma rota não fica “observável” porque recebeu cinco chamadas de logger. Ela fica observável quando uma pessoa consegue entender o incidente e agir.

## Onde o Evlog CLI funciona bem

A ferramenta é especialmente útil em três situações.

**Projetos criados rapidamente com IA.** Agentes costumam entregar o caminho feliz e tratamentos genéricos de erro. O mapa oferece uma revisão adicional antes que velocidade vire dívida operacional.

**Times que já possuem logs, mas não confiam neles.** O CLI ajuda a localizar handlers que emitem apenas contexto técnico ou deixam operações sensíveis sem auditoria explícita.

**Pipelines que precisam impedir regressões.** A linha de base transforma observabilidade em um critério verificável, semelhante a cobertura de teste e lint.

Também há uma vantagem editorial para a arquitetura: o mapa cria uma linguagem comum. Produto, desenvolvimento e operação conseguem discutir quais fluxos merecem contexto sem começar pela escolha de uma plataforma de logs.

## Onde ele não resolve o problema

O Evlog CLI trabalha com análise estática. Ele não sabe:

- quais rotas recebem mais tráfego;
- quais erros estão acontecendo agora;
- quanto tempo uma consulta levou;
- se um evento chegou corretamente ao destino;
- se um alerta acordou a pessoa certa;
- se o contexto registrado é verdadeiro em todas as condições.

A análise de imports também possui limites, e a sensibilidade de uma rota é inferida por heurísticas. Um nome contendo `auth` pode elevar a exigência, enquanto uma operação crítica com nome genérico pode escapar da classificação.

Por isso, a arquitetura completa continua precisando de runtime, destino e operação:

1. o Evlog CLI verifica a intenção no código;
2. o runtime Evlog monta eventos durante a execução;
3. Axiom, OTLP ou outro destino armazena e permite consultar;
4. métricas e traces mostram tendência e desempenho;
5. alertas e runbooks transformam evidência em resposta.

O CLI fortalece essa cadeia, mas não é a cadeia inteira.

## Vale a pena adotar?

Para projetos Nuxt que já usam Evlog, a resposta tende a ser sim. O custo de rodar o mapa é baixo, o resultado é legível e a linha de base permite melhorar sem uma migração grande.

Para quem ainda não usa o runtime, vale começar pelo `map --no-write`. Ele pode revelar a qualidade atual do tratamento de erros antes de qualquer decisão de plataforma. Depois, o `init --dry-run` mostra o que seria alterado.

O cuidado principal está na maturidade. A versão analisada é recente, suporta um conjunto específico de frameworks e pode mudar regras com frequência. Fixar versão, revisar falsos positivos e evitar perseguir o 100 por vaidade são práticas obrigatórias.

Nosso resultado de 35/100 não virou uma lista automática de alterações. Virou um mapa de risco. Autenticação e fluxos críticos entram primeiro; exceções intencionais recebem justificativa; rotas simples não ganham complexidade apenas para aumentar o número.

Essa é a decisão de negócio por trás da ferramenta: **reduzir o tempo e a incerteza de uma falha sem transformar cada linha do produto em telemetria**.

## Checklist para começar

- [ ] execute `evlog map --no-write` localmente;
- [ ] salve o resultado JSON como evidência inicial;
- [ ] revise primeiro autenticação, pagamento, webhooks e permissões;
- [ ] diferencie falta de contexto de exceção intencional;
- [ ] nunca registre senha, token, CPF, telefone ou conteúdo privado;
- [ ] crie uma linha de base antes de bloquear o CI;
- [ ] defina um score mínimo igual ou próximo ao estado atual;
- [ ] eleve o mínimo somente depois de melhorias reais;
- [ ] fixe a versão do CLI;
- [ ] combine análise estática com logs, métricas, traces e alertas de produção.

## Perguntas frequentes

### O Evlog CLI envia meu código para algum serviço?

Segundo a documentação, o CLI lê o código-fonte localmente e não precisa ser implantado com a aplicação. Como em qualquer dependência de desenvolvimento, revise a versão e as políticas do pacote antes de adotá-lo em projetos sensíveis.

### Preciso usar Evlog no runtime para executar o mapa?

Você pode rodar o mapa para analisar o projeto, mas as recomendações são voltadas às práticas e APIs do ecossistema Evlog. Para transformar a instrumentação em eventos reais, o runtime e um destino de observabilidade precisam estar configurados.

### Um score baixo significa que meu aplicativo é ruim?

Não. Significa que o código analisado não atende a parte das verificações atuais do CLI. O score deve orientar uma revisão por risco, não substituir testes, métricas reais ou julgamento técnico.

### Devo exigir 100/100?

Raramente no começo. Use uma linha de base e impeça regressões. Eleve a exigência conforme os fluxos mais importantes forem instrumentados de maneira útil.

### O Evlog CLI substitui Sentry, Axiom ou Cloudflare Observability?

Não. Ele avalia cobertura no código antes do deploy. Plataformas de observabilidade recebem, armazenam e consultam o que acontece durante a execução.

### Fontes e leitura recomendada

- [Evlog CLI: visão geral](https://www.evlog.dev/cli/overview)
- [Como funciona o evlog map](https://www.evlog.dev/cli/map)
- [Evlog CLI no CI](https://www.evlog.dev/cli/ci)
- [Regras e composição do score](https://www.evlog.dev/cli/rules)
- [Configuração com evlog init](https://www.evlog.dev/cli/init)