API Reference / Ops e health

Ops e health

Un endpoint per il monitoraggio: metriche HTTP in-process, stato della coda dei workflow, versione e uptime del processo. È la fonte da cui capire, a colpo d'occhio, se l'app e il worker stanno bene.

GET /api/ops/health admin

Riservato agli amministratori: la profondità della coda è un'informazione operativa sensibile. Restituisce sempre 200 con lo stato corrente.

Parametri

Nessuno: l'endpoint non accetta parametri di query, path o body. Serve solo l'header Authorization: Bearer <accessToken> di un amministratore.

Richiesta

curl "https://crm.tuodominio.it/api/ops/health" \
  -H "Authorization: Bearer <accessToken>"

const res = await fetch("https://crm.tuodominio.it/api/ops/health", {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const { data } = await res.json();

Risposta · 200

json

{
  "success": true,
  "data": {
    "status": "ok",
    "version": "1.0.0",
    "uptimeMs": 3600000,
    "http": { "total": 1284, "byClass": { "2xx": 1200, "4xx": 80, "5xx": 4 }, … },
    "workflowQueue": {
      "byStatus": { "pending": 2, "running": 1, "done": 940, "dead": 0 },
      "oldestPendingAgeMs": 1200,
      "staleRunningCount": 0,
      "staleThresholdMs": 600000
    },
    "timestamp": "2026-07-07T15:24:00.000Z"
  }
}

01Come leggerlo

Campo	Significato
version · uptimeMs	Versione dell'app e da quanto è attivo il processo (utile dopo un deploy).
http	Contatori delle risposte per classe di stato (2xx/4xx/5xx) e latenza. Sono in-process: si azzerano al riavvio e sono per-istanza.
workflowQueue.byStatus	Numero di job per stato nella coda.
workflowQueue.oldestPendingAgeMs	Età del job in attesa più vecchio: se cresce, la coda si sta accumulando (worker fermo o lento).
workflowQueue.staleRunningCount	Job rimasti "running" oltre la soglia: tipicamente un worker morto a metà; il reaper li recupera da solo.
workflowQueue.staleThresholdMs	Soglia oltre cui un job "running" è considerato stale. Allineata a quella del reaper.

02Esiti

Stato	Codice	Quando
200	·	Stato corrente restituito. L'endpoint risponde sempre 200 quando autorizzato.
401	`UNAUTHORIZED`	Token assente, scaduto o non valido.
403	`FORBIDDEN`	Utente autenticato ma non amministratore.

Nota · controllo del worker

Non c'è un endpoint separato per il worker: la sua salute si deduce da qui. Un oldestPendingAgeMs che sale a fronte di job pending è il segnale che il worker non sta consumando la coda. Vedi Worker e salute operativa.

← PrecedenteFatturazione Successiva →Audit log