Monitorare il media server con Prometheus e Grafana

Quven ha una piccola API di sola lettura per le dashboard di casa. Emetti una chiave dalle impostazioni del server, la mandi come header e leggi cosa contiene il server e cosa sta riproducendo. La chiave non può cambiare nulla: è come sono costruite le rotte, non una regola scritta.

1. Emetti una chiave

1. Apri le Impostazioni, vai su Server e cerca la card delle chiavi di integrazione.
2. Dai alla chiave un nome che avrà ancora senso fra sei mesi, per esempio “Homepage”.
3. Copia il segreto dal pannello che si apre. Compare una volta sola, perché il server ne conserva solo un hash. Dopo, l’elenco mostra gli ultimi caratteri.

Se perdi una chiave, revocala ed emettine un’altra. La revoca è immediata e non si annulla.

2. Mandala con ogni richiesta

curl -H "X-Quven-Key: qvn_il-tuo-segreto" \
  http://il-tuo-server:5181/api/integration/v1/statistics

curl -H "Authorization: Bearer qvn_il-tuo-segreto" \
  http://il-tuo-server:5181/api/integration/v1/statistics

La maggior parte delle dashboard offre solo un campo Authorization, ed è per questo che funziona anche la forma bearer. Se le mandi entrambe, vince l’header dedicato.

3. Scegli la rotta

Sono sei, tutte GET, sotto /api/integration/v1.

Rotta	Risposta
/server	L’installazione: nome, versione, avvio del processo e versione dell’API che parla
/statistics	Film, serie, episodi, file e byte su disco
/libraries	Ogni libreria con il numero di file e l’ora dell’ultima scansione
/sessions	Cosa è in riproduzione: titolo, posizione, durata e se transcodifica
/metrics	Gli stessi conteggi in testo Prometheus
/history	Cosa è stato riprodotto, dal più recente, a pagine con limit e offset

/statistics è il riquadro che vogliono quasi tutti:

{
  "movieCount": 2284,
  "showCount": 91,
  "episodeCount": 4137,
  "fileCount": 6602,
  "totalStorageBytes": 41203847561216
}

• /libraries conta i file, quindi una libreria che non ne ha ancora compare con la prima scansione che ne trova.
• /sessions indica ogni quanto chiedere in refreshAfterSeconds. Rispettalo: una dashboard che interroga ogni secondo carica il server per niente e può rallentare la riproduzione di tutti.
• /history dice cosa è stato riprodotto e quando, mai chi lo ha chiesto.

Il riferimento campo per campo è su quven.tv/api/integration/v1, con il documento OpenAPI accanto per i client generati. Entrambi nascono dalle rotte del server.

4. Leggila con Prometheus

/metrics permette a Grafana di leggere il server senza un exporter:

scrape_configs:
  - job_name: quven
    metrics_path: /api/integration/v1/metrics
    authorization:
      type: Bearer
      credentials: qvn_il-tuo-segreto
    static_configs:
      - targets: ["il-tuo-server:5181"]

5. Interroga a basso costo con ETag

Ogni lettura porta un ETag. Rimandalo come If-None-Match e un server che non è cambiato risponde 304 senza corpo: sul relay è la differenza tra un poll che costa un round trip e uno che costa un elenco di libreria. L’eccezione è /sessions: la risposta porta l’istante in cui è stata presa, quindi cambia ogni volta.

6. Provala nel browser

La pagina di riferimento esegue queste letture contro il tuo server: metti l’indirizzo e una chiave nella barra in alto e premi Send. La richiesta va dal tuo browser al tuo server e da nessun’altra parte. Tre condizioni possono bloccarla, e la pagina dice quale riconosce:

• Un server in http semplice, raggiunto da quella pagina, a meno che sia su questa macchina.
• Un indirizzo che il browser non raggiunge.
• Un server più vecchio della console, che non ammette ancora quella pagina.

Il pulsante curl le copre tutte e tre.

Controlla che il server sia attivo

GET /health/live risponde 200 con la parola Healthy e non vuole nessuna chiave, quindi un monitor può interrogarlo senza tenersi un segreto. /health/ready richiede autenticazione e non è fatto per questo. L’uptime è startedUtc su /server e quven_server_start_time_seconds nelle metriche.

Cosa non restituisce mai

• Percorsi delle cartelle. /libraries nasce dalle statistiche del catalogo e non legge mai la configurazione delle librerie, quindi un percorso come /mnt/tank/media/films non può trapelare.
• Identità di chi guarda. /sessions mostra che qualcosa è in riproduzione e che cosa, mai chi lo guarda.

Limiti e versioni

• Una chiave ha diritto a 120 richieste al minuto, contate per chiave: un’integrazione configurata male esaurisce il proprio budget e lascia stare le altre.
• Un server tiene 25 chiavi attive. Se ci arrivi, quasi certamente hai dimenticato di revocarne qualcuna.
• Le rotte stanno sotto /api/integration/v1, separate da quelle che usano le app Quven, e questo percorso resta stabile fra una versione dei client e l’altra.
• Un server più vecchio dell’API risponde 404 a tutto. Chiedi prima /server e leggi apiVersion.

Se una chiave trapela

Chi la possiede può leggere il catalogo e vedere cosa è in riproduzione. Non può avviare una scansione, cambiare una libreria, toccare un file o emettere un’altra chiave, perché la gestione delle chiavi sta dietro il login del proprietario. Revocare l’originale la chiude.

Questo confine è il motivo per cui l’API ha questa forma: dare a una dashboard il token del tuo account sarebbe stato più semplice da costruire e molto meno sicuro.