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.