Pular para conteúdo

Logs e diagnóstico

Logs

Todos os serviços de backend registram em JSON, uma linha por evento, no stdout (QV_LOG_JSON=true):

{"ts":"2026-10-14T17:23:54Z","level":"INFO","service":"engine","logger":"quantix.engine.ratings","msg":"ratings: {...}"}
{"ts":"2026-10-14T17:24:10Z","level":"WARNING","service":"collector","logger":"quantix.collector","msg":"performance falhou: ...","device":"array-00"}

Campos extras quando presentes: device_id, device, plugin, collector, job, duration_ms, rows, exc (stack trace). Nível em QV_LOG_LEVEL (DEBUG, INFO, WARNING, ERROR). QV_LOG_JSON=false gera texto legível (útil em desenvolvimento).

make logs S=engine                                   # compose
docker compose logs --since 1h collector | grep -i falhou
docker compose logs api | jq -r 'select(.level=="ERROR") | [.ts,.logger,.msg] | @tsv'
kubectl -n quantix logs deploy/qv-quantix-vision-ingestor -f

Rotação: driver json-file com QV_LOG_MAX_SIZE (50 MB) × QV_LOG_MAX_FILE (5) por container.

Serviço Mensagens úteis
api bootstrap concluído, Primeiro acesso: usuário 'admin' senha temporária: …, modo tudo-em-um…
collector coletor <nome> iniciando (transporte=…, plugins=N), dispositivo agendado, inventário publicado, … falhou
ingestor ingestor pronto, ingestão de métricas ativa (a cada 60 s, com o total de linhas), snapshot aplicado
engine engine iniciada, um resumo por job, job X falhou
automation executor de automação pronto, executando runbook …

Saúde e status

Endpoint Autenticação Uso
GET /healthz (nginx, porta 80/8080) não balanceador: o nginx está no ar
GET /api/health não liveness/readiness: {"status": "ok"\|"degraded", "postgres": true, "tsdb": true, "version": "1.0.0"}
GET /api/v1/system/status view dispositivos e coletores por status, objetos, achados abertos, tamanho do PostgreSQL, tabelas do ClickHouse e ingestão dos últimos 10 min
GET /api/v1/collectors view heartbeat, versão, host e estatísticas de cada coletor
GET /metrics não (restrinja no nginx) Prometheus: quantix_info{version}, quantix_uptime_seconds, quantix_devices{status}, quantix_open_findings{severity}, quantix_entities
ClickHouse :9363/metrics rede interna métricas nativas do ClickHouse
NATS :8222/varz, /jsz rede interna conexões, stream QV_DATA, consumidores

Exemplo de scrape (Prometheus):

- job_name: quantix
  scheme: https
  metrics_path: /metrics
  static_configs: [{ targets: ["quantix.empresa.local"] }]

Coletando um pacote de diagnóstico

docker compose ps > diag-ps.txt
docker compose logs --since 2h > diag-logs.txt
curl -sk https://localhost/api/health > diag-health.json
TOKEN=qv_...   # token de API
curl -sk -H "Authorization: Bearer $TOKEN" https://localhost/api/v1/system/status > diag-status.json

Remova segredos antes de compartilhar: os logs não contêm credenciais, mas o .env sim.