Pular para conteúdo

Observabilidade e Diagnóstico

Este guia estabelece os padrões de monitoramento, rastreabilidade de requisições e o runbook de resposta rápida a incidentes para a equipe técnica responsável pela sustentação da plataforma EcomSmart Agents.


Matriz de Healthchecks dos Serviços

Os serviços abaixo expõem endpoints aplicacionais úteis para diagnóstico. Eles não equivalem todos a um healthcheck Docker: confirme também a coluna STATUS de docker compose ps.

Serviço Endpoint de Saúde Tipo Retorno Esperado
Flow Gateway http://127.0.0.1:${FLOW_GATEWAY_PORT:-3080}/health HTTP GET 200 "ok\n"
Landing http://landing:8080/health HTTP GET 200 "ok\n" (endpoint existe; o Compose não declara healthcheck próprio)
WhatsApp Entrypoint http://whatsapp-entrypoint:8000/ HTTP GET {"status": "ok"}
WhatsApp $\leftrightarrow$ DB http://whatsapp-entrypoint:8000/api/v1/health/merchants-db HTTP GET {"connected": true, ...}
Frontend Entrypoint http://frontend-entrypoint:7000/health HTTP GET {"status": "ok"}
Agente B2B http://b2b:8004/api/v1/health HTTP GET {"status": "ok"}
Marketing Campaigns http://marketing-campaigns:7002/health HTTP GET status e conectividade com banco
GenAI Wrapper http://genai-wrapper:8000/health HTTP GET {"status": "ok"}
Weaviate Vector http://weaviate:8080/v1/.well-known/ready HTTP GET 200 OK
PostgreSQL pg_isready -U merchants_admin -d merchants CLI accepting connections

Rastreabilidade e Correlação de Requisições

Para rastrear qualquer incidente que ocorra desde o clique do cliente no WhatsApp até a confirmação de pagamento na loja, correlacione os seguintes identificadores:

flowchart LR
    wamid[1. msg_id / wamid: Meta Webhook] --> phone[2. Telefone: 55DD9XXXXXXXX]
    phone --> merchant[3. merchant_id: UUID da Loja]
    merchant --> fsm[4. FSM State: Redis fsm:store:phone]
    fsm --> order[5. order_id: WooCommerce REST API]

    style wamid fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
    style phone fill:#f0f9ff,stroke:#0284c7,stroke-width:1.5px,color:#0369a1
    style merchant fill:#fefce8,stroke:#d97706,stroke-width:1.5px,color:#92400e
    style fsm fill:#faf5ff,stroke:#9333ea,stroke-width:1.5px,color:#6b21a8
    style order fill:#f0fdf4,stroke:#16a34a,stroke-width:1.5px,color:#166534

Comandos de Busca de Logs por Identificador

# Localizar o recebimento de uma mensagem da Meta pelo ID
docker compose -f infra/docker-compose.yaml logs whatsapp-entrypoint | grep "wamid.HB..."

# Filtrar todos os eventos de um cliente pelo telefone normalizado (13 dígitos)
docker compose -f infra/docker-compose.yaml logs b2c | grep "5584999999999"

# Inspecionar falhas de sincronização de um pedido específico
docker compose -f infra/docker-compose.yaml logs woocommerce-wrapper | grep "order_id=12345"

Inspeção Rápida de Infraestrutura

1. Redis (Locks, FSM e Sessões)

# Acessar a CLI do Redis interativamente
docker compose -f infra/docker-compose.yaml exec redis redis-cli

# Verificar estado atual da máquina de vendas de um cliente
GET fsm:STORE_ID:5584999999999:state

# Verificar o lock de checkout de uma conversa B2C
TTL checkout:lock:STORE_ID:5584999999999

# Procurar chaves sem bloquear o Redis. Substitua a máscara pelo contexto investigado.
SCAN 0 MATCH 'fsm:STORE_ID:5584999999999:*' COUNT 100

2. PostgreSQL (Integridade e Auditoria)

# Consultar número de lojistas ativos
docker compose -f infra/docker-compose.yaml exec merchants-db \
  psql -U merchants_admin -d merchants -c "SELECT id, company_name, status FROM platform.merchants;"

# Inspecionar últimas execuções do pipeline de marketing
docker compose -f infra/docker-compose.yaml exec merchants-db \
  psql -U merchants_admin -d merchants -c "SELECT * FROM platform.marketing_pipeline_execucoes ORDER BY criado_em DESC LIMIT 5;"
# Listar imagens salvas no bucket de produtos
docker compose -f infra/docker-compose.yaml exec minio-init mc ls local/product-images

Runbook de Resolução de Incidentes

Caso 1: O cliente envia mensagem no WhatsApp e não recebe resposta

  1. Verificar Webhook da Meta: Consulte os logs do whatsapp-entrypoint:
    docker compose -f infra/docker-compose.yaml logs --tail=100 whatsapp-entrypoint
    
    Se houver registros com HMAC signature verification failed, o META_APP_SECRET no .env foi alterado ou está incorreto.
  2. Verificar Despacho Interno: Confira se o evento foi repassado com status 202 Accepted para o container b2c. Se o B2C estiver indisponível, reinicie o container:
    docker compose -f infra/docker-compose.yaml restart b2c
    

Caso 2: A conversa do cliente parou no meio do checkout

  1. Verificar Locks Órfãos no Redis: Procure pela chave checkout:lock:{store_id}:{sender} e verifique o TTL. Não apague chaves de uma conversa ativa sem registrar o contexto e confirmar que a operação não está em execução.
  2. Verificar Erros de Frete no WooCommerce: Consulte os logs do woocommerce-wrapper. Se a API do Melhor Envio retornar erro de CEP inválido ou produto sem peso/dimensões, a conversa permanece aguardando revalidação do lojista.

Caso 3: Queda no serviço de IA (Gemini ou OpenAI)

  1. O genai-wrapper possui fallback de contingência e retentativas exponenciais com tenacity.
  2. Se ambos os provedores apresentarem falha de cota, o Agente B2C entra em modo defensivo (soft-fallback), recomendando os produtos mais populares do catálogo local sem inferência semântica.