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;"
3. MinIO (Mídias e Fotos de Catálogo)
# 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
- Verificar Webhook da Meta:
Consulte os logs do
whatsapp-entrypoint: Se houver registros comHMAC signature verification failed, oMETA_APP_SECRETno.envfoi alterado ou está incorreto. - Verificar Despacho Interno:
Confira se o evento foi repassado com status
202 Acceptedpara o containerb2c. Se o B2C estiver indisponível, reinicie o container:
Caso 2: A conversa do cliente parou no meio do checkout
- 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. - 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)
- O
genai-wrapperpossui fallback de contingência e retentativas exponenciais comtenacity. - 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.