Superviser votre serveur multimédia avec Prometheus et Grafana

Quven dispose d’une petite API en lecture seule pour les tableaux de bord domestiques. Vous créez une clé depuis les réglages du serveur, vous l’envoyez dans un en-tête et vous lisez ce que le serveur contient et ce qu’il diffuse. La clé ne peut rien modifier : c’est ainsi que les routes sont construites, et non une simple règle.

1. Créer une clé

1. Ouvrez Paramètres, allez dans Serveur et trouvez la carte Clés d’intégration.
2. Donnez à la clé un nom que vous comprendrez encore dans six mois, comme « Homepage ».
3. Copiez le secret dans le panneau qui s’ouvre. Il n’apparaît qu’une fois, car le serveur n’en conserve qu’une empreinte. La liste affiche ensuite les derniers caractères.

Si vous perdez une clé, révoquez-la et créez-en une autre. La révocation est immédiate et irréversible.

2. L’envoyer avec chaque requête

curl -H "X-Quven-Key: qvn_your-secret-here" \
  http://your-server:5181/api/integration/v1/statistics

curl -H "Authorization: Bearer qvn_your-secret-here" \
  http://your-server:5181/api/integration/v1/statistics

La plupart des tableaux de bord n’offrent qu’un champ Authorization, d’où la forme bearer, qui fonctionne aussi. Si vous envoyez les deux, l’en-tête dédié l’emporte.

3. Choisir la route

Les six sont en GET, sous /api/integration/v1.

Route	Réponse
/server	L’installation : nom, version, démarrage du processus et version d’API parlée
/statistics	Films, séries, épisodes, fichiers et octets sur le disque
/libraries	Chaque bibliothèque avec le nombre de fichiers et l’heure de sa dernière analyse
/sessions	Ce qui est en cours de lecture : titre, position, durée et transcodage ou non
/metrics	Les mêmes comptes au format texte de Prometheus
/history	Ce qui a été lu, du plus récent au plus ancien, paginé par limit et offset

/statistics est la vignette que la plupart des gens veulent :

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

• /libraries compte des fichiers : une bibliothèque qui n’en contient aucun apparaît avec la première analyse qui trouve quelque chose.
• /sessions indique à quelle fréquence l’interroger dans refreshAfterSeconds. Respectez-la : un tableau de bord qui interroge chaque seconde charge le serveur pour rien et peut ralentir la lecture de tous les autres.
• /history dit ce qui a été lu et quand, jamais qui l’a demandé.

La référence champ par champ se trouve sur quven.tv/api/integration/v1, avec le document OpenAPI à côté pour les clients générés. Les deux sont construits à partir des routes propres du serveur.

4. L’interroger avec Prometheus

/metrics permet à Grafana de lire le serveur sans exporteur :

scrape_configs:
  - job_name: quven
    metrics_path: /api/integration/v1/metrics
    authorization:
      type: Bearer
      credentials: qvn_your-secret-here
    static_configs:
      - targets: ["your-server:5181"]

5. Interroger à moindre coût avec ETag

Chaque lecture porte un ETag. Renvoyez-le dans If-None-Match : un serveur inchangé répond 304 sans corps, ce qui, à travers un relais, fait la différence entre une interrogation qui coûte un aller-retour et une qui coûte la liste d’une bibliothèque. L’exception est /sessions : sa réponse porte l’instant où elle a été prise, elle diffère donc à chaque fois.

6. L’essayer dans le navigateur

La page de référence exécute ces lectures contre votre propre serveur : saisissez l’adresse et une clé dans la barre du haut, puis appuyez sur Send. La requête va de votre navigateur à votre serveur et nulle part ailleurs. Trois choses l’arrêtent, et la page dit lesquelles elle peut :

• Un serveur en http simple, atteint depuis cette page, sauf s’il se trouve sur cette machine.
• Une adresse que votre navigateur ne peut pas atteindre.
• Un serveur plus ancien que la console, qui n’admet pas encore cette page.

Le bouton curl couvre les trois.

Vérifier que le serveur est actif

GET /health/live répond 200 avec le mot Healthy et n’exige aucune clé : une sonde peut donc l’interroger sans détenir de secret. /health/ready exige une authentification et n’est pas prévu pour cela. La durée de fonctionnement elle-même est startedUtc sur /server et quven_server_start_time_seconds dans les métriques.

Ce qu’elle ne renvoie jamais

• Les chemins de dossiers. /libraries est construit à partir des statistiques du catalogue et ne lit jamais la configuration des bibliothèques : un chemin comme /mnt/tank/media/films ne peut donc pas fuiter.
• L’identité du spectateur. /sessions montre que quelque chose est lu et ce que c’est, jamais qui le regarde.

Limites et versions

• Une clé a droit à 120 requêtes par minute. Le compte est par clé : une intégration mal configurée épuise son propre budget et épargne les autres.
• Un serveur détient 25 clés actives. Si vous atteignez ce plafond, vous avez presque certainement oublié de révoquer quelque chose.
• Les routes vivent sous /api/integration/v1, à part de celles qu’utilisent les applications Quven, et ce chemin reste stable d’une version du client à l’autre.
• Un serveur plus ancien que l’API répond 404 sur tout. Interrogez d’abord /server et lisez son apiVersion.

Si une clé fuite

Quiconque la détient peut lire votre catalogue et voir ce qui est en cours de lecture. Cette personne ne peut ni lancer une analyse, ni modifier une bibliothèque, ni toucher un fichier, ni créer une autre clé, car la gestion des clés se trouve derrière une connexion de propriétaire. Révoquer la clé d’origine y met fin.

Cette frontière explique la forme de l’API : confier à un tableau de bord le jeton de votre compte aurait été plus simple à construire et bien moins sûr.