---
title: Documentação de Monitoramento
slug: helper/documentacao-de-monitoramento
createdAt: 2026-11-19T14:26:41.147Z
---

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

```javascript
┌─────────────┐  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)

```javascript
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

```javascript
- 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

```javascript
- 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

```javascript
- 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

```javascript
- 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)

```javascript
- 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)

```javascript
- 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)

```javascript
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)

1. **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.
2. **Backlog BullMQ sem métrica** — `GET /api/filas` tem os números; falta Gauge Prometheus (ver §6).
3. **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}`.
4. `/metrics` **aberto** — sem token no código (API e worker). *Mitigação:* NetworkPolicy/ingress deny + scrape interno.
5. **NLU sem métricas Prometheus** — só `/health` + logs em `nlu_log` (tenant). Taxa de `baixa_confianca`/`ambiguo` é visível em `/api/nlu/stats`.
6. **k8s não cobre callbridge/LiveKit** — voz não monitorável no cluster até existir manifest.
7. `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:

1. **Pipeline:** `outbox_pendentes` (com anotação de deploy) · rate de `jobs_total` por fila/status · p95 `job_duration_seconds` · dead\_letter acumulado.
2. **Canais:** `entregas_total` por broker/status (taxa de falha %) · `mensagens_total{entrada}` · webhooks 401.
3. **API:** RPS, 5xx %, p95 por rota.
4. **Infra:** Postgres (conexões/400, tx longa, tamanho) · Redis (memória, AOF) · disco/FDs.
5. **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 📦).
