Health & Sistema

2. Health & Sistema#

GET/health#

Verifica se o serviço e suas dependencias (MySQL, Redis) estão funcionando.

Auth: Nenhuma

Resposta 200:

json
{
  "status": "ok",
  "service": "catcher-api",
  "checks": {
    "mysql": "ok",
    "redis": "ok"
  }
}

Resposta 503 (degradado):

json
{
  "status": "degraded",
  "service": "catcher-api",
  "checks": {
    "mysql": "ok",
    "redis": "error"
  }
}

GET/ready#

Verifica se todas as dependencias (MySQL, Redis, S3) estão funcionando.

Auth: Nenhuma

Resposta 200:

json
{
  "status": "ready",
  "checks": {
    "mysql": "ok",
    "redis": "ok",
    "s3": "ok",
    "email": "configured",
    "proxy_audit": "ok"
  }
}

Os campos s3 e proxy_audit so aparecem quando S3 / pool de proxy estão configurados. email e sempre presente (configured ou disabled) e e informativo. proxy_audit em estado degraded ou stale faz o /ready responder 503.

Resposta 503 (degradado):

json
{
  "status": "degraded",
  "checks": {
    "mysql": "ok",
    "redis": "error"
  }
}

GET/metrics#

Metricas Prometheus.

Auth: Desabilitado por padrão quando METRICS_BEARER_TOKEN estiver vazio. Para expor:

  • defina METRICS_BEARER_TOKEN e envie Authorization: Bearer <METRICS_BEARER_TOKEN>
  • ou habilite explicitamente ALLOW_PUBLIC_METRICS=true

Se ALLOW_PUBLIC_METRICS=false e METRICS_BEARER_TOKEN estiver vazio, a API responde 401.

Resposta: Texto no formato Prometheus exposition.

Exemplos de series expostas (não exaustivo): biazap_active_instances, biazap_connection_states, biazap_messages_total, biazap_send_latency_seconds_*, biazap_webhook_failures_total, biazap_send_failures_total, biazap_throttle_pauses_total, biazap_realtime_events_dropped_total (eventos descartados quando o cliente SSE/WS não acompanha o hub), biazap_queue_depth, biazap_redis_latency_seconds_*, biazap_s3_latency_seconds_*.

Stealth / fingerprint hardening (scaffolding inicial):

  • biazap_send_interval_ms
  • biazap_connection_opens_total
  • biazap_connection_closes_total
  • biazap_warmup_phase
  • biazap_warmup_daily_sent
  • biazap_warmup_daily_cap
  • biazap_fingerprint_platform_total
  • biazap_fingerprint_utls_spec_total
  • biazap_fingerprint_utls_pool_active_size
  • biazap_fingerprint_utls_assignments_total
  • biazap_fingerprint_utls_probe_total
  • biazap_fingerprint_utls_burn_total
  • biazap_fingerprint_city_total
  • biazap_hygiene_applied_total
  • biazap_send_blocked_total
  • biazap_humanize_typing_emitted_total
  • biazap_stealth_debug_mode_active
  • biazap_ban_events_total
  • biazap_audit_emit_failed_total
  • biazap_audit_emit_dropped_total
  • biazap_appversion_fetch_failed_total

As series do Stealth Mode aparecem no /metrics desde o bootstrap, mesmo antes dos produtores definitivos, para que dashboards e canaries possam ser preparados sem esperar as tasks posteriores. Em biazap_send_blocked_total, o label reason agora inclui inbound_first quando a instância opt-in recusa um outbound para chat sem inbound previo na janela configurada.


GET/one/metrics (porta própria, só loopback) — métricas de negócio para o Catcher One#

Exposição Prometheus 0.0.4 das métricas de negócio que o Catcher One lê (contrato one.business-metrics.v1, fonte HTTP staging-app/prod-app, leitura a cada 60 s). Não é servido na porta da API: é um listener próprio, com registro Prometheus próprio (só estas séries), ligado só quando ONE_METRICS_ADDR está definido.

Auth: nenhuma — por isso só escuta em loopback. ONE_METRICS_ADDR com host que não seja loopback é recusado (o endpoint não sobe e a API segue). Em container (ONE_METRICS_IN_CONTAINER=1) aceita 0.0.0.0, e o compose publica a porta só no 127.0.0.1 do host. A porta é definida por ambiente (staging e PROD dividem o mesmo box Eveo):

Ambiente Endereço no host Onde se define Estado
Staging (docker) 127.0.0.1:9464 deploy/staging-eveo/docker-compose.yml (ONE_METRICS_ADDR=0.0.0.0:9464 + ONE_METRICS_IN_CONTAINER=1, porta publicada só em 127.0.0.1) ligado
PROD (systemd nativo) 127.0.0.1:9465 drop-in só da API deploy/eveo-prod/biazap-api.service.d/one-metrics.conf → /etc/systemd/system/biazap-api.service.d/ (fora do biazap.env, que é compartilhado com os workers) ligado (T5.7, 12/11/2026) pelo deploy declarado de PROD: scripts/deploy-eveo-onbox.sh instala os *.conf desse diretório (só da biazap-api), daemon-reload e restart só do biazap-api; o promotor classifica o drop-in como app (kind go, nenhum worker reinicia). Conferir no host, só leitura: ssh <box> bash -s < scripts/one-metrics-compare.sh
Variável Padrão Efeito
ONE_METRICS_ADDR vazio (desligado) endereço do listener, ex. 127.0.0.1:9465
ONE_METRICS_IN_CONTAINER — 1 permite 0.0.0.0 dentro do container
ONE_METRICS_REFRESH 30s período do coletor (mín. 5 s); cada atualização loga one-metrics: refresh com took_ms, parts_ms (o funil é a parte messages) e tenants — nível info nas 3 primeiras coletas após o start (custo legível no journal de PROD), warn acima de 10 s, debug nas demais

Só GET/HEAD em /one/metrics (outro método: 405; outro caminho: 404). Content-Type: text/plain; version=0.0.4. A leitura serializa o último retrato do coletor (atualizado em segundo plano), então responde em milissegundos. Nenhum rótulo leva telefone, nome, e-mail, JID, IP ou id de instância/empresa; destination é só o host do webhook (sem usuário, porta, caminho ou consulta; destino por IP vira ip-literal).

Série Tipo Rótulos De onde vem
biazap_instances gauge status, engine (whatsmeow, wwebjs, official=meta_cloud) tenant_instances das empresas ativas, só as não excluídas (deleted_at IS NULL): instância excluída não entra em nenhum status (nem DELETED/DELETING), nem na saúde, nem no uptime
biazap_instances_health gauge health (healthy, degraded=stale/degraded, critical=offline/critical_offline/banned/logged_out, unknown=pending) regra do NOC (health.EvaluateTier); desligadas de propósito ficam fora
biazap_connectivity_degraded / _banned gauge — saúde degraded / status BANNED
biazap_connectivity_flapping gauge — instâncias com ≥2 quedas e 1 volta (connection.update) ou flap_detected na última hora
biazap_connectivity_uptime gauge — % do tempo conectado nas últimas 24 h (instâncias que deveriam estar online), por connection.update
biazap_connectivity_reconnects_total counter engine connection.update connected novos em event_logs
biazap_connectivity_proxy_errors_total counter kind (connect_timeout, tls_handshake, proxy_auth, proxy_error, connection_reset, connection_refused, dns, other) diagnóstico autoreconnect_proxy_failure novo em event_logs
biazap_messages_in_total / _out_total counter kind (text, media, other) linhas novas de messages (por id) criadas há no máximo 1 h — histórico importado (history sync / historical) não é tráfego
biazap_delivery_sent_total counter — saída que deixou a fila: sent_at ou failed_at no intervalo
biazap_delivery_server_ack_total / _delivered_total / _read_total / _failed_total counter — sent_at / delivered_at / read_at / failed_at no intervalo
biazap_send_latency histogram (ms) — sent_at − queued_at
biazap_delivery_latency histogram (ms) — delivered_at − sent_at
biazap_webhooks_deliveries_total counter destination (host), outcome (ok, retried=ok após >1 tentativa, failed) delivery_logs novos (válvulas do operador fora)
biazap_webhooks_queue gauge queue (pending, retry=atrás de uma entrega falha, dlq=Asynq default arquivado) cursor de cada webhook ativo × event_logs
biazap_send_queue_depth gauge state (pending, retrying, held) send outbox + held_sends (só de instâncias não excluídas, as mesmas de biazap_instances) + Asynq default
biazap_media_standby gauge — pending_media_emits
biazap_media_deferred_near_exhaustion gauge — mídia em standby quase esgotando: linhas de pending_media_emits com attempts >= 5 (de ~8 tentativas do reconciliador wwebjs), somadas nas empresas ativas — o mesmo número de fleet.near_exhaustion em GET /v1/admin/media-resilience (limiar único onemetrics.MediaNearExhaustionThreshold). Leitura incompleta ou estourada mantém o último valor (alerta não some com um 0 inventado)
biazap_brightdata_balance / _consumed / _runway_days gauge — effective_balance / pending_costs / runway_days de GET /v1/admin/balance do broker — o mesmo número do cartão «Saldo Bright Data» do console; broker fora → as linhas somem; runway_known=false → sem runway_days
biazap_health_up gauge component (api, mysql, redis, s3, worker) checagem a cada atualização (worker = GET WORKER_RPC_URL/health)
biazap_health_check_latency histogram (ms) component tempo da checagem
biazap_companies gauge status, billing banco mestre: ops/metrics/companies.sql (empresas não excluídas por status × billing_status)
biazap_brightdata_ips gauge status banco mestre: ops/metrics/brightdata_ips.sql (proxy_ips do provedor bright-data)
biazap_proxy_connect_failures_total counter (acumulado no banco) — banco mestre: ops/metrics/proxy_connect_failures.sql (SUM(total_connect_failures))
biazap_proxy_bans_total counter (acumulado no banco) — banco mestre: ops/metrics/proxy_bans.sql (SUM(ban_count))
biazap_instances_registered gauge — a lista de instâncias do console (GET /v1/admin/instances): ops/metrics/instances_registered.sql (tenant_instances com deleted_at IS NULL) rodada no banco de cada empresa de companies (todas, como o console) e somada. Banco de tenant que não abre fica fora, como no console; contagem que falha mantém o último total. Até 12/11/2026 contava instance_schemas do mestre, que PROD não preenche mais (dava 0)

Contadores e histogramas começam em zero quando a API sobe (o One grava o incremento e trata o reinício); o histórico anterior nunca é contado. Recibos (delivered/read) são procurados nas mensagens das últimas ~6 h. As 5 métricas de banco do catálogo (biazap.companies, .brightdata.ips, .proxy.connect_failures, .proxy.bans no mestre e .instances.registered nos bancos de tenant) são servidas aqui (32 famílias no total, com biazap_media_deferred_near_exhaustion; as 3 do Bright Data somem com o broker fora): o coletor roda as mesmas consultas de ops/metrics/*.sql (texto fixado por teste) com a conexão que a API já tem — as 4 do mestre numa transação READ ONLY e a de instâncias como um COUNT por tenant —, antes das demais partes por tenant. Assim nenhuma credencial de banco sai da BiaZap e o One lê PROD só por HTTP em loopback. Falha de uma consulta mantém o último valor dela; antes da 1ª leitura a família é omitida (nunca um 0 inventado num contador). Nomes: catálogo com . → _, contadores com _total.

bash
# no host de staging
curl -s 127.0.0.1:9464/one/metrics | grep '^biazap_brightdata'
curl -s 127.0.0.1:9464/one/metrics | grep -E '^biazap_(companies|brightdata_ips|proxy_(connect_failures|bans)_total|instances_registered)'
curl -s 127.0.0.1:9464/one/metrics | grep '^biazap_media'   # standby + deferred_near_exhaustion

POST/v1/internal/proxy-pong#

Endpoint interno usado pelo health-check de proxy. O worker envia um POST assinado através do IP dedicado da instância; a API responde com o IP observado para provar que o tráfego saiu pelo proxy esperado. Não é um endpoint para clientes da API.

Auth: HMAC-SHA256 no corpo (signature), usando PROXY_HEALTH_SECRET. O timestamp é aceito apenas dentro de uma janela de 5 minutos.

Request:

json
{
  "version": "v1",
  "pool_ip_id": 7,
  "expected_ip": "200.160.45.35",
  "nonce": "f0f1c2a3b4d5e6f7",
  "timestamp": 1779724800,
  "signature": "9f1c7b..."
}

Resposta 200:

json
{
  "echo_nonce": "f0f1c2a3b4d5e6f7",
  "observed_ip": "200.160.45.35",
  "x_forwarded_for": "200.160.45.35",
  "user_agent": "biazap-proxy-pong/1",
  "received_at": "2026-05-25T12:00:00Z",
  "server_time": "2026-05-25T12:00:00Z",
  "match": true
}

Erros:

  • 400 BAD_JSON — corpo inválido.
  • 401 INVALID_SIGNATURE — assinatura inválida, replay ou timestamp fora da janela.
  • 503 PROXY_HEALTH_DISABLED — PROXY_HEALTH_SECRET não configurado.

GET/v1/monitoring/errors/{id}#

Retorna o JSON completo de um incidente capturado (toda resposta 4xx — exceto 401/403/404/429 — e toda 5xx geram um arquivo INC-YYYY-MM-DD-XXXX). Endpoint público, sem JWT/cookie: a autenticação e feita pelo header X-Incident-Key.

Auth: Header X-Incident-Key: <INCIDENT_KEY> (segredo de ambiente). Sem JWT.

Path param:

Param Formato Descricao
id INC-AAAA-MM-DD-XXXX ID do incidente (4 caracteres finais são [A-Z0-9])

Resposta 200: O JSON do incidente — incident_id, service, timestamp, trace_id, request{method,url,path,remote_addr,user_agent,headers,body}, response{status,headers,body,duration_ms}, error{code,message,stack}, context{}.

Erros (este endpoint usa um envelope aninhado {"error":{"code","message"}}, distinto do envelope unificado da seção 19):

Status code Quando
400 INCIDENT_ID_INVALID id não casa com INC-AAAA-MM-DD-XXXX
401 INCIDENT_KEY_INVALID Header X-Incident-Key ausente ou inválido
404 INCIDENT_NOT_FOUND Incidente expirou (>7 dias) ou nunca existiu
500 INCIDENT_READ_FAILED Falha ao ler o arquivo do incidente