Health & Sistema

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: connection refused"
  }
}

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_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/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:

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):