Documentação de Monitoramento
Catálogo de métricas reais do código e as triggers (regras de alerta) prontas para Prometheus/Alertmanager, com runbooks. Cobre API, worker, relay/outbox, filas, NLU, LLM/RAG, atendimento humano, voz, banco, Redis, MinIO e Keycloak.
1. Arquitetura de monitoramento
┌─────────────┐ scrape /metrics (:8000, SEM auth — r…
│ API FastAPI │ ◄──────────────────────────────┐
└─────────────┘ │
┌─────────────┐ scrape /metrics (:9100) │
│ Worker │ ◄──────────────────────────────┼─────… Teams/on-call
│ (+relay/ │ /health/ready (DB+Redis) │
│ sweepers) │ │ … plataforma.json)
└─────────────┘ │
NLU :8001/health · postgres_exporter · redis_exporter · node_exporter · blackbox (web,
keycloak, livekit)Alvos de coleta
Alvo | Endpoint | Observação |
|---|---|---|
API | GET {ROOT_PATH}/metrics (:8000) | ⚠️ Sem proteção no código (sem token) — expon[…] interna / bloqueie no ingress |
Worker | GET /metrics (:9100) | é aqui que vive a Gauge outbox_pendentes (só o worker a atualiza) |
Readiness | API {ROOT_PATH}/health/ready · worker :9100/health/ready | 503 se DB ou Redis caírem; MinIO é informativo (nunca derruba) |
NLU | GET :8001/health | {ok, model, redis, rerank_carregado} — sem métricas Prometheus próprias (probe via blackbox) |
callbridge | — | não expõe health/metrics (lacuna — ver §5) |
PostgreSQL / Redis / host | exporters :9187 / :9121 / :9100* | *usar porta alternativa p/ node_exporter (worker já usa 9100) |
Console (web) / Keycloak / LiveKit | blackbox probe | /healthz nginx · /health/ready KC · TCP 7880 LiveKit |
2. Catálogo de métricas (reais, do código)
2.1 Aplicação (core/metrics.py — convenção: baixa cardinalidade, nunca tenant_id em label)
Métrica | Tipo | Labels | Uso |
|---|---|---|---|
http_requests_total | Counter | method, path, status | tráfego/erros HTTP (path = template da rota) |
http_request_duration_seconds | Histogram | method, path | latência de API |
mensagens_total | Counter | direcao | mensagens processadas ⚠️ direcao="saida" declar[…] alimentada — não basear alerta nela |
entregas_total | Counter | broker, status | entregas ao provedor (enviado/falha/…) — emitida em processing/entrega.py |
jobs_total | Counter | queue, status | jobs (ok/failed/rejeitado/dead_letter) — emitida em channels/lifecycle.py |
job_duration_seconds | Histogram | queue | duração de job |
outbox_pendentes | Gauge | — | sinal nº 1: linhas de outbox não despachadas (atualizada a cada tick do relay, só no worker) |
2.2 Sinais indiretos (sem métrica dedicada — usar como proxy)
O que monitorar | Como |
|---|---|
Relay parado | outbox_pendentes crescendo sem drenar ou métrica estagnada (relay é quem a atualiza) |
Sweepers parados (inatividade/rollup/humor) | sem heartbeat próprio — logam em stdout; proxy: worker down (readiness) cobre o processo inteiro |
Backlog BullMQ (wait/active/failed por fila) | não há Gauge Prometheus — só GET /api/filas (JSON). Recomendação em §6 |
Dead-letter (conteúdo) | GET /api/admin/dead-letter (job_log) — a contagem sai por jobs_total{status="dead_letter"} |
Qualidade NLU / uso e teto de LLM | endpoints de negócio GET /api/nlu/stats e GET /api/ia/uso (não-Prometheus) |
2.3 Infra (exporters)
Redis: redis_up, redis_memory_used_bytes, redis_aof_last_write_status · Postgres: pg_up, pg_stat_activity_count (limite 400), pg_stat_activity_max_tx_duration, pg_database_size_bytes · Host: node_filefd_allocated, node_filesystem_avail_bytes · Blackbox: probe_success.
3. Triggers (regras de alerta)
Convenções: critical = acordar alguém; warning = horário comercial; info = tendência. As 6 regras já versionadas em infra/observability/alerts.yml estão marcadas com 📦 (mantidas/refinadas).
3.1 Disponibilidade (critical)
groups:
- name: coi-disponibilidade
rules:
- alert: CoiApiDown
expr: up{job="api"} == 0
for: 2m
labels: { severity: critical, team: coi }
annotations:
summary: "API do AURA fora do ar"
description: "Webhooks dos provedores começam a falhar (mensagens de clientes se perdem no provedor se persistir). Verificar pod/container e /health/ready."
- alert: CoiWorkerDown
expr: up{job="worker"} == 0
for: 2m
labels: { severity: critical, team: coi }
annotations:
summary: "Worker do AURA fora do ar"
description: "Sem worker: NENHUMA mensagem é processada/entregue (outbox acumula), atendimento humano sem distribuição/SLA, timeouts de fluxo param. A ingestão continua gravando (outbox) — nada se perde, mas nada anda."
- alert: CoiApiNaoPronta
# readiness = DB + Redis (gates duros); MinIO não derruba
expr: probe_success{instance=~".*health/ready.*", job="blackbox-coi-api"} == 0
for: 3m
labels: { severity: critical, team: coi }
annotations: { summary: "API de pé porém NOT READY (Postgres ou Redis indisponível)" }
- alert: CoiNluDown
expr: probe_success{instance=~".*nlu.*"} == 0
for: 5m
labels: { severity: warning, team: coi }
annotations:
summary: "Microserviço NLU fora do ar"
description: "classify é FAIL-OPEN (fluxos segu[…] humano); embed FALHA → indexação de KB para. Degradaç[…] motivo=baixa_confianca em /api/nlu/stats."
- alert: CoiConsoleDown
expr: probe_success{instance=~".*web.*healthz.*"} == 0
for: 3m
labels: { severity: critical, team: coi }
annotations: { summary: "Console (nginx/web) fora do ar — atendentes sem acesso" }
- alert: CoiKeycloakDown
expr: probe_success{instance=~".*keycloak.*"} == 0
for: 3m
labels: { severity: critical, team: coi }
annotations:
summary: "Keycloak indisponível"
description: "Novos logins do console param (sessões com refresh válido seguem por um tempo). Widget do cliente NÃO depende do Keycloak (exceto bloco auth OIDC interno)."3.2 Outbox e relay — o coração do pipeline
- name: coi-outbox-relay
rules:
- alert: OutboxAcumulado # 📦 existente
expr: outbox_pendentes > 500
for: 5m
labels: { severity: warning, team: coi }
annotations:
summary: "Outbox acumulando ({{ $value }} pendentes)"
description: "Relay não drena no ritmo da ingestão. Ver: worker vivo? Redis ok? pico de campanha? Conferir GET /api/filas."
- alert: OutboxRepresadoCritico
expr: outbox_pendentes > 5000 and (delta(outbox_pendentes[10m]) > 0)
for: 10m
labels: { severity: critical, team: coi }
annotations:
summary: "Outbox >5k e crescendo — pipeline efetivamente parado"
description: "Mensagens de clientes não estão sendo processadas. Confirmar relay: SELECT count(*) FROM control.outbox WHERE dispatched_at IS NULL; reiniciar worker se necessário."
- alert: RelayEstagnado
# A Gauge é atualizada a cada tick do relay (0,5s). Se o valor não muda E há pendências, o relay travou.
expr: outbox_pendentes > 0 and (changes(outbox_pendentes[10m]) == 0)
for: 10m
labels: { severity: critical, team: coi }
annotations:
summary: "Relay do outbox aparenta estar travado (métrica estagnada com pendências)"
description: "Worker roda mas o loop do relay morreu (procurar '[relay] erro:' no stdout). Reiniciar worker."3.3 Filas / jobs
- name: coi-jobs
rules:
- alert: JobsFalhando # 📦 existente
expr: sum by (queue) (rate(jobs_total{status="failed"}[5m])) > 0.2
for: 5m
labels: { severity: warning, team: coi }
annotations:
summary: "Jobs falhando na fila {{ $labels.queue }}"
description: "Backoff exponencial em curso (5 tentativas). Se persistir vira dead_letter. Ver logs do worker + job_log."
- alert: DeadLetterRecebendo # 📦 existente
expr: sum by (queue) (increase(jobs_total{status="dead_letter"}[10m])) > 0
labels: { severity: critical, team: coi }
annotations:
summary: "Jobs esgotando retries na fila {{ $labels.queue }}"
description: "Mensagens/entregas sendo abandonadas. Inspecionar GET /api/admin/dead-letter e reprocessar via POST /api/filas/reprocessar após corrigir a causa."
- alert: TenantJobsRejeitados # 📦 existente
expr: sum(rate(jobs_total{status="rejeitado"}[10m])) > 0.05
for: 10m
labels: { severity: info, team: coi }
annotations:
summary: "Jobs rejeitados por tenant inativo/suspenso"
description: "Clientes de tenant suspenso continuam mandando mensagem. Avaliar desativar canal/avisar comercial."
- alert: JobsLentos
expr: histogram_quantile(0.95, sum by (le, queue) (rate(job_duration_seconds_bucket[10m]))) > 30
for: 10m
labels: { severity: warning, team: coi }
annotations:
summary: "p95 de job na fila {{ $labels.queue }} > 30s"
description: "Fila 'mensagens': nó ia/webhook lento (LLM_TIMEOUT=60s, HTTP_TIMEOUT=15s)? Fila 'kb_indexar': normal p/ docs grandes. Com concurrency=5, jobs lentos derrubam a vazão da fila inteira."3.4 Entrega e provedores
- name: coi-entrega
rules:
- alert: ErroDeProvider # 📦 existente
expr: sum by (broker) (rate(entregas_total{status="falha"}[5m])) > 0.1
for: 5m
labels: { severity: warning, team: coi }
annotations:
summary: "Falhas de entrega no broker {{ $labels.broker }}"
description: "Credencial expirada? Provedor fora? Template rejeitado? O sistema também dispara e-mail 'canal_queda'. Testar conexão do canal no console."
- alert: ProviderFalhaConcentrada
expr: |
sum by (broker) (rate(entregas_total{status="falha"}[10m]))
/
clamp_min(sum by (broker) (rate(entregas_total[10m])), 0.001) > 0.25
for: 10m
labels: { severity: critical, team: coi }
annotations:
summary: "Broker {{ $labels.broker }} com >25% de falha de entrega"
description: "Clientes deste canal sem resposta. Não há circuit breaker por provider no AURA — a falha continua consumindo retries; agir rápido."
- alert: EntregaParada
# Mensagens entram mas nada sai — quebra silenciosa do caminho de saída
expr: |
sum(increase(mensagens_total{direcao="entrada"}[15m])) > 50
and sum(increase(entregas_total[15m])) == 0
for: 15m
labels: { severity: critical, team: coi }
annotations:
summary: "Entradas chegando (15min) mas NENHUMA entrega saindo"
description: "Fila broker_output travada, outbox represado ou driver quebrando antes do envio. Ver GET /api/filas e dead-letter."3.5 HTTP / API
- name: coi-http
rules:
- alert: LatenciaHTTPAlta # 📦 existente
expr: histogram_quantile(0.95, sum by (le, path) (rate(http_request_duration_seconds_bucket[5m]))) > 1
for: 5m
labels: { severity: warning, team: coi }
annotations: { summary: "p95 > 1s em {{ $labels.path }}" }
- alert: ApiErro5xx
expr: |
sum(rate(http_requests_total{status=~"5.."}[5m]))
/
clamp_min(sum(rate(http_requests_total[5m])), 0.001) > 0.02
for: 5m
labels: { severity: critical, team: coi }
annotations: { summary: "API com >2% de respostas 5xx" }
- alert: WebhookRejeitado401
# Assinatura de webhook falhando (secret trocado no provedor / WEBHOOK_REQUIRE_SIGNATURE sem secret configurado)
expr: sum(rate(http_requests_total{path=~".*/webhook/.*", status="401"}[10m])) > 0.05
for: 10m
labels: { severity: critical, team: coi }
annotations:
summary: "Webhooks de provedor sendo rejeitados (401)"
description: "Mensagens de clientes estão sendo DESCARTADAS na porta. Conferir webhook_secret do canal vs painel do provedor."
- alert: SemMensagensHorarioComercial
expr: |
sum(increase(mensagens_total{direcao="entrada"}[1h])) == 0
and on() (hour() >= 11 and hour() <= 21) # 08–18h BRT
for: 1h
labels: { severity: info, team: coi }
annotations: { summary: "Nenhuma mensagem de entrada há 1h em horário comercial — webhook/túnel/ingress quebrado?" }3.6 Redis e PostgreSQL (critical)
- name: coi-infra
rules:
- alert: RedisDown
expr: redis_up == 0
for: 1m
labels: { severity: critical, team: coi }
annotations:
summary: "Redis fora do ar — filas, WS e locks parados"
description: "Ingestão via outbox continua gravando (Postgres) — nada se perde; ao voltar, o relay drena. WS do widget cai (reconnect automático 1s). Readiness da API/worker vai a 503."
- alert: RedisAofFalhando
expr: redis_aof_last_write_status == 0
for: 1m
labels: { severity: critical, team: coi }
annotations: { summary: "AOF do Redis falhando (disco?) — durabilidade de jobs em risco" }
- alert: PostgresDown
expr: pg_up == 0
for: 1m
labels: { severity: critical, team: coi }
annotations: { summary: "PostgreSQL fora do ar — plataforma inoperante (readiness 503 em API e worker)" }
- alert: PostgresConexoesAltas
# max_connections=400 (compose); pools: API 10×2 workers uvicorn × réplicas + worker
expr: sum(pg_stat_activity_count) > 320
for: 5m
labels: { severity: warning, team: coi }
annotations:
summary: "Conexões Postgres >80% de 400"
description: "Escalou réplicas recentemente? Próximo passo recomendado: PgBouncer transaction pooling (app compatível: statement_cache_size=0 + SET LOCAL)."
- alert: PostgresTransacaoLonga
expr: pg_stat_activity_max_tx_duration > 300
for: 5m
labels: { severity: warning, team: coi }
annotations: { summary: "Transação aberta >5min — pode travar relay (FOR UPDATE) e locks de conversa" }
- alert: DiscoEnchendo
expr: node_filesystem_avail_bytes{mountpoint="/"} / node_filesystem_size_bytes{mountpoint="/"} < 0.15
for: 10m
labels: { severity: critical, team: coi }
annotations: { summary: "Disco <15% — risco p/ WAL do Postgres, AOF do Redis e MinIO (anexos/gravações)" }3.7 Atendimento humano e voz (sinais de negócio)
- name: coi-negocio
rules:
- alert: TransbordoSemAgentes
# Não há métrica direta; proxy: taxa de handoff registrada nas entregas de aviso + logs.
# RECOMENDAÇÃO (§6): expor Gauge fila_humana_aguardando. Enquanto isso, alerta via
# relatório/synthetic: probe autenticado em /api/atendimento (agentes online == 0 em horário comercial).
expr: vector(0) # placeholder — implementar após métrica dedicada (ver §6)
labels: { severity: none }
annotations: { summary: "(pendente de métrica fila_humana_aguardando / agentes_online)" }
- alert: UsoLlmProximoDoTeto
# Sem métrica Prometheus de tokens — usar synthetic via GET /api/ia/uso (json_exporter)
# ou o e-mail nativo. Placeholder até expor Gauge ia_tokens_mes / ia_teto_mes.
expr: vector(0)
labels: { severity: none }
annotations: { summary: "(pendente — hoje o teto mensal é visível em /api/ia/uso; status teto_mensal em ia_usage_log)" }4. Roteamento (Alertmanager)
route:
receiver: coi-teams
group_by: [alertname, severity]
group_wait: 30s
group_interval: 5m
repeat_interval: 4h
routes:
- matchers: [ severity = critical ]
receiver: coi-oncall
repeat_interval: 30m
- matchers: [ severity = info ]
receiver: coi-teams
repeat_interval: 24h
inhibit_rules:
- source_matchers: [ alertname = CoiApiDown ]
target_matchers: [ alertname =~ "LatenciaHTTPAlta|ApiErro5xx|WebhookRejeitado401|SemMensagens.*" ]
- source_matchers: [ alertname = CoiWorkerDown ]
target_matchers: [ alertname =~ "Outbox.*|Relay.*|Jobs.*|DeadLetter.*|EntregaParada" ]
- source_matchers: [ alertname = RedisDown ]
target_matchers: [ alertname =~ "Outbox.*|Jobs.*|EntregaParada|CoiApiNaoPronta" ]
- source_matchers: [ alertname = PostgresDown ]
target_matchers: [ severity =~ "warning|info" ]
=====5. Lacunas de cobertura (registrar como pendência)
- callbridge sem health/metrics — processo single-replica (chamadas nativas WhatsApp) sem endpoint de saúde. Mitigação: monitorar o container (docker/k8s liveness por processo) e o canal Redis callbridge:cmd. Correção: adicionar mini HTTP server como o do worker.
- Backlog BullMQ sem métrica — GET /api/filas tem os números; falta Gauge Prometheus (ver §6).
- Sweepers sem heartbeat — inatividade/rollup/humor só logam; se um deles morrer com o processo vivo, não há alerta. Correção: Gauge sweeper_last_run_timestamp{sweeper}.
- /metrics aberto — sem token no código (API e worker). Mitigação: NetworkPolicy/ingress deny + scrape interno.
- NLU sem métricas Prometheus — só /health + logs em nlu_log (tenant). Taxa de baixa_confianca/ambiguo é visível em /api/nlu/stats.
- k8s não cobre callbridge/LiveKit — voz não monitorável no cluster até existir manifest.
- mensagens_total{direcao="saida"} declarada e não alimentada — corrigir emissão ou remover a label (as triggers deste doc usam entregas_total para o lado de saída).
6. Instrumentação recomendada (pequena, alto retorno)
Métrica nova | Tipo | Onde emitir | Habilita |
|---|---|---|---|
bull_queue_depth{queue,state} | Gauge | sweep do worker lendo bull:{q}:wait/active/delayed/failed (mesma fonte do /api/filas) | alertas de backlog por fila (como no Disparos) |
fila_humana_aguardando{sem tenant} + agentes_online | Gauge | _sweep_inatividade (agregado global) | alerta "clientes esperando e 0 agentes" |
sweeper_last_run_timestamp{sweeper} | Gauge | fim de cada sweep | detectar sweeper morto |
nlu_classificacoes_total{motivo} | Counter | nlu_client.classificar | qualidade NLU (baixa_confianca/ambiguo em alta) |
ia_tokens_mes / ia_teto_mes | Gauge | ia_base.controles_cfg | alerta de teto mensal de LLM antes de estourar |
health HTTP no callbridge | — | mini servidor como o do worker | liveness/readiness de voz |
7. Dashboards recomendados (Grafana)
O repo já tem infra/observability/grafana/.../plataforma.json — estender com:
- Pipeline: outbox_pendentes (com anotação de deploy) · rate de jobs_total por fila/status · p95 job_duration_seconds · dead_letter acumulado.
- Canais: entregas_total por broker/status (taxa de falha %) · mensagens_total{entrada} · webhooks 401.
- API: RPS, 5xx %, p95 por rota.
- Infra: Postgres (conexões/400, tx longa, tamanho) · Redis (memória, AOF) · disco/FDs.
- Negócio (via endpoints JSON): NLU stats, uso de IA vs teto, filas humanas — até a instrumentação do §6.
8. Runbooks (primeiros 5 minutos)
Trigger | Diagnóstico | Ação |
|---|---|---|
CoiWorkerDown / OutboxRepresadoCritico | :9100/health; SELECT count(*) FROM control.outbox WHERE dispatched_at IS NULL | Restart do worker — o relay drena o represado sozinho (idempotente, jobId=outbox.id) |
RelayEstagnado | stdout do worker: [relay] erro: | Restart do worker; se recorrente, olhar exceção no loop |
DeadLetterRecebendo | GET /api/admin/dead-letter (erro real por job) | Corrigir causa → POST /api/filas/reprocessar |
ErroDeProvider / ProviderFalhaConcentrada | Console → Canais → Testar conexão; e-mail canal_queda chegou? | Renovar credencial/token do canal; conferir painel do provedor |
WebhookRejeitado401 | Secret do canal vs painel do provedor | Re-sincronizar webhook_secret; validar WEBHOOK_REQUIRE_SIGNATURE |
CoiNluDown | curl nlu:8001/health | Restart NLU; enquanto isso classify é fail-open (fluxo segue, mais handoff) — reindexações falhas se recuperam |
CoiApiNaoPronta | /health/ready diz qual gate caiu (db/redis) | Atacar o dependente; MinIO degradado NÃO derruba — anexos falham isolados |
PostgresConexoesAltas | quem consome: pg_stat_activity | PgBouncer antes de subir max_connections |
9. Checklist de implantação
- Subir --profile observ (Prometheus+Grafana versionados) ou apontar o Prometheus central para api:8000{ROOT_PATH}/metrics e worker:9100/metrics
- Restringir /metrics por rede (NetworkPolicy/ingress) — não há auth no código
- Adicionar exporters: postgres, redis, node (porta ≠ 9100), blackbox (web/keycloak/NLU/LiveKit/health-ready)
- Carregar as regras deste documento (substituem/estendem infra/observability/alerts.yml) e validar com promtool check rules
- Alertmanager com roteamento por severidade + inibições (§4)
- Registrar as 7 lacunas do §5 como backlog e priorizar o §6 (métricas novas — poucas linhas cada)
- Teste de fogo em homologação: matar o worker e confirmar CoiWorkerDown + OutboxAcumulado + drenagem pós-restart
- Revisar thresholds contra o volume real do tenant após 2 semanas de baseline
Fontes
Baseado nas métricas e comportamentos reais do código (commit e33494b): core/metrics.py, worker.py (relay/sweepers/:9100), channels/lifecycle.py (status de jobs), processing/entrega.py, api.py (health/metrics sem auth), e no esqueleto existente infra/observability/ (6 regras incorporadas 📦).