2. Health & Sistema#
GET/health#
Verifica se o serviço e suas dependencias (MySQL, Redis) estão funcionando.
Auth: Nenhuma
Resposta 200:
{
"status": "ok",
"service": "catcher-api",
"checks": {
"mysql": "ok",
"redis": "ok"
}
}
Resposta 503 (degradado):
{
"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:
{
"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):
{
"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_TOKENe envieAuthorization: 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_msbiazap_connection_opens_totalbiazap_connection_closes_totalbiazap_warmup_phasebiazap_warmup_daily_sentbiazap_warmup_daily_capbiazap_fingerprint_platform_totalbiazap_fingerprint_utls_spec_totalbiazap_fingerprint_utls_pool_active_sizebiazap_fingerprint_utls_assignments_totalbiazap_fingerprint_utls_probe_totalbiazap_fingerprint_utls_burn_totalbiazap_fingerprint_city_totalbiazap_hygiene_applied_totalbiazap_send_blocked_totalbiazap_humanize_typing_emitted_totalbiazap_stealth_debug_mode_activebiazap_ban_events_totalbiazap_audit_emit_failed_totalbiazap_audit_emit_dropped_totalbiazap_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.
# 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:
{
"version": "v1",
"pool_ip_id": 7,
"expected_ip": "200.160.45.35",
"nonce": "f0f1c2a3b4d5e6f7",
"timestamp": 1779724800,
"signature": "9f1c7b..."
}
Resposta 200:
{
"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_SECRETnã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 |