Observabilidade e Monitoramento

Este documento descreve a stack de observabilidade do projeto: rastreamento de erros e traces (HyperDX), analytics de comportamento de usuário (GA4, Clarity, Meta Pixel), logs de processo (PM2) e monitoramento de uptime.

1. Stack de Observabilidade

Ferramenta	Propósito	Onde Configurar	Variável de Ambiente
HyperDX	Traces, logs server-side, erros de aplicação	Dashboard HyperDX	`HYPERDX_API_KEY`, `OTEL_SERVICE_NAME`
PM2	Logs de processo e métricas de runtime	Servidor de produção	— (configurado no `ecosystem.config.js`)
Google Analytics 4	Comportamento do usuário, funil de compra	Admin GA4 + `NEXT_PUBLIC_GA4_ID`	`NEXT_PUBLIC_GA4_ID`
Microsoft Clarity	Mapas de calor, gravações de sessão	Dashboard Clarity + `NEXT_PUBLIC_CLARITY_ID`	`NEXT_PUBLIC_CLARITY_ID`
Meta Pixel	Conversões de anúncios, remarketing	Admin da loja (SiteSettings)	`NEXT_PUBLIC_MP_PIXEL_ID`
UptimeRobot	Monitoramento de disponibilidade 24/7	Dashboard UptimeRobot	— (configurado externamente)

2. HyperDX

2.1 Setup via `instrumentation.ts`

O HyperDX é inicializado via o Next.js Instrumentation Hook (instrumentation.ts na raiz do projeto). Esse hook é executado uma única vez no início do processo Node.js, antes de qualquer requisição ser processada.

// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { init } = await import("@hyperdx/node-opentelemetry");
    init({
      apiKey: process.env.HYPERDX_API_KEY,
      service: process.env.OTEL_SERVICE_NAME ?? "ljvemasearomas",
    });
  }
}

O guard process.env.NEXT_RUNTIME === "nodejs" é obrigatório para evitar que o SDK tente inicializar no Edge Runtime, que não suporta os módulos OpenTelemetry nativos.

2.2 Variáveis de Ambiente

Variável	Descrição	Exemplo
`HYPERDX_API_KEY`	Chave de API do projeto no HyperDX	`hdx_...`
`OTEL_SERVICE_NAME`	Nome do serviço exibido no dashboard	`ljvemasearomas-prod`

2.3 O Que é Capturado Automaticamente

Traces HTTP: todas as requisições recebidas e externas (fetch, axios)
Logs server-side: console.log, console.error, console.warn são automaticamente capturados e correlacionados com o trace correspondente
Erros não tratados: exceções que escapam para o runtime são capturadas e enviadas com stack trace
Métricas de banco de dados: queries Prisma aparecem como spans filhos dos traces HTTP

2.4 Como Acessar o Dashboard

Acesse app.hyperdx.io
Selecione o projeto ljvemasearomas
Na aba Search, filtre por service.name = ljvemasearomas-prod
Para ver erros: filtre por level = error ou exception.type exists
Para ver traces lentos: ordene por duration decrescente

2.5 Como Adicionar um Span Customizado

Para instrumentar uma operação específica (ex.: geração de NF-e, cálculo de frete):

import { trace } from "@opentelemetry/api";

const tracer = trace.getTracer("ljvemasearomas");

export async function calcularFrete(cep: string, peso: number) {
  return tracer.startActiveSpan("frete.calcular", async (span) => {
    try {
      span.setAttribute("frete.cep", cep);
      span.setAttribute("frete.peso_gramas", peso);

      const resultado = await chamarApiCorreios(cep, peso);

      span.setAttribute("frete.opcoes_retornadas", resultado.length);
      return resultado;
    } catch (err) {
      span.recordException(err as Error);
      span.setStatus({ code: 2, message: (err as Error).message });
      throw err;
    } finally {
      span.end();
    }
  });
}

3. PM2 — Logs de Processo

3.1 Comandos Essenciais

# Ver logs em tempo real (últimas 100 linhas + streaming)
pm2 logs ljvemasearomas

# Ver apenas as últimas N linhas (sem streaming)
pm2 logs ljvemasearomas --lines 200 --nostream

# Monitor interativo (CPU, memória, logs em tempo real)
pm2 monit

# Status de todos os processos
pm2 status

# Reiniciar sem downtime (reload gracioso)
pm2 reload ljvemasearomas

# Reiniciar com downtime (mata e reinicia)
pm2 restart ljvemasearomas

3.2 Paths dos Arquivos de Log

Configurados no ecosystem.config.js (ou pm2 start com flags):

/home/<usuario>/.pm2/logs/ljvemasearomas-out.log    → stdout (logs normais)
/home/<usuario>/.pm2/logs/ljvemasearomas-error.log  → stderr (erros)

Para localizar os paths exatos no servidor:

pm2 info ljvemasearomas | grep "log file"

3.3 Rotação de Logs

Para evitar que os arquivos de log cresçam indefinidamente, instalar o módulo de rotação:

pm2 install pm2-logrotate

# Configurar rotação diária, mantendo 7 dias
pm2 set pm2-logrotate:max_size 50M
pm2 set pm2-logrotate:retain 7
pm2 set pm2-logrotate:compress true
pm2 set pm2-logrotate:rotateInterval "0 0 * * *"

4. Google Analytics 4

4.1 Configuração

O GA4 é carregado via components/ui/analytics-scripts.tsx, que injeta o script gtag.js no <head> da aplicação quando NEXT_PUBLIC_GA4_ID está definido.

NEXT_PUBLIC_GA4_ID=G-XXXXXXXXXX

Se a variável não estiver definida, o script não é injetado (sem erros no console).

4.2 Eventos Disparados

Evento GA4	Quando é disparado	Dados Enviados
`view_item`	Página de produto visualizada	`item_id`, `item_name`, `price`
`add_to_cart`	Produto adicionado ao carrinho	`item_id`, `item_name`, `price`, `quantity`
`begin_checkout`	Usuário inicia o checkout	`value`, `currency`, `items[]`
`purchase`	Pedido confirmado com sucesso	`transaction_id`, `value`, `items[]`

4.3 Onde Configurar no Admin

A ativação e desativação do GA4 é gerenciada via variável de ambiente — não há toggle no painel admin. Para desabilitar, remover NEXT_PUBLIC_GA4_ID do ambiente e reiniciar o servidor.

5. Microsoft Clarity

5.1 Configuração

O Clarity é carregado via components/ui/clarity-script.tsx:

NEXT_PUBLIC_CLARITY_ID=xxxxxxxxxx

5.2 Funcionalidades

Mapas de calor: visualização agregada de cliques, toques e scroll por página
Gravações de sessão: replay de sessões reais de usuários (anonimizado)
Insights automáticos: Clarity detecta "rage clicks", cliques em elementos não interativos e dead clicks

5.3 Acessar o Dashboard

Acesse clarity.microsoft.com
Selecione o projeto correspondente ao site
Aba Recordings para sessões individuais
Aba Heatmaps para visualização agregada por URL

LGPD: as gravações do Clarity são anonimizadas por padrão. Verificar se o aviso de cookies do site informa sobre este tipo de rastreamento comportamental.

6. Meta Pixel

6.1 Configuração

O ID do Pixel é configurado via painel admin da loja (SiteSettings), não via .env fixo. O valor é lido da tabela SiteSettings no banco e exposto como:

NEXT_PUBLIC_MP_PIXEL_ID=<id-do-pixel>

Isso permite trocar o Pixel sem redeploy — apenas salvar nas configurações do admin e aguardar o próximo request (valor é lido em Server Component com cache: 'no-store' ou similar).

6.2 Eventos de Conversão

Evento Meta Pixel	Quando é disparado
`ViewContent`	Página de produto visualizada
`AddToCart`	Produto adicionado ao carrinho
`InitiateCheckout`	Início do checkout
`Purchase`	Pedido confirmado (com `value` e `currency`)

6.3 Verificação

Usar a extensão Meta Pixel Helper (Chrome/Firefox) para verificar se os eventos estão sendo disparados corretamente em cada etapa do funil.

7. Alertas de Uptime

7.1 UptimeRobot (Plano Gratuito)

O UptimeRobot gratuito permite até 50 monitores com verificação a cada 5 minutos, com alertas por e-mail.

Passo a passo para configurar:

Criar conta em uptimerobot.com
Clicar em + Add New Monitor
Preencher:
- Monitor Type: HTTP(s)
- Friendly Name: ljvemasearomas - Produção
- URL: https://seu-dominio.com.br
- Monitoring Interval: 5 minutes
Em Alert Contacts, adicionar o e-mail para receber alertas
Clicar em Create Monitor

Alertas configurados por padrão:

Notificação quando o site fica fora do ar (status != 200)
Notificação quando o site volta ao ar

7.2 Better Uptime (Alternativa com Mais Recursos)

O Better Uptime oferece plano gratuito com verificação a cada 3 minutos, alertas por e-mail, Slack e telefone, além de página de status pública.

Vantagens em relação ao UptimeRobot:

Verificação a cada 3 minutos (vs 5 min no plano free do UptimeRobot)
Página de status pública em status.seu-dominio.com (útil para comunicar incidentes)
Integração nativa com Slack e PagerDuty

8. Health Check

8.1 Endpoint `/api/health`

Se o endpoint /api/health estiver implementado, ele deve retornar:

{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "version": "1.0.0",
  "database": "connected"
}

Use este endpoint como probe nos monitores de uptime — é mais confiável que monitorar / porque:

Não depende de CDN ou cache
Verifica ativamente a conectividade com o banco de dados
Resposta leve (sem renderização HTML)

8.2 Configuração no UptimeRobot com Health Check

Monitor Type: HTTP(s)
URL: https://seu-dominio.com.br/api/health
Keyword: "status":"ok"    ← falha se essa string não aparecer na resposta

8.3 Teste Manual do Health Check

curl -s https://seu-dominio.com.br/api/health | jq .

# Resposta esperada:
# {
#   "status": "ok",
#   "database": "connected"
# }

Se a rota /api/health não existir, usar GET / como probe básico (verifica apenas que o servidor está respondendo).

1. Stack de Observabilidade​

2. HyperDX​

2.1 Setup via instrumentation.ts​

2.2 Variáveis de Ambiente​

2.3 O Que é Capturado Automaticamente​

2.4 Como Acessar o Dashboard​

2.5 Como Adicionar um Span Customizado​

3. PM2 — Logs de Processo​

3.1 Comandos Essenciais​

3.2 Paths dos Arquivos de Log​

3.3 Rotação de Logs​

4. Google Analytics 4​

4.1 Configuração​

4.2 Eventos Disparados​

4.3 Onde Configurar no Admin​

5. Microsoft Clarity​

5.1 Configuração​

5.2 Funcionalidades​

5.3 Acessar o Dashboard​

6. Meta Pixel​

6.1 Configuração​

6.2 Eventos de Conversão​

6.3 Verificação​

7. Alertas de Uptime​

7.1 UptimeRobot (Plano Gratuito)​

7.2 Better Uptime (Alternativa com Mais Recursos)​

8. Health Check​

8.1 Endpoint /api/health​

8.2 Configuração no UptimeRobot com Health Check​

8.3 Teste Manual do Health Check​