Ihren Medienserver mit Prometheus und Grafana überwachen

Quven bietet eine kleine schreibgeschützte API für Dashboards im Heimnetz. Sie erstellen in den Servereinstellungen einen Schlüssel, senden ihn als Header und lesen, was der Server enthält und was er gerade abspielt. Der Schlüssel kann nichts ändern: So sind die Routen aufgebaut, das ist keine bloße Richtlinie.

1. Einen Schlüssel erstellen

1. Öffnen Sie die Einstellungen, wechseln Sie zu Server und suchen Sie die Karte für Integrationsschlüssel.
2. Geben Sie dem Schlüssel einen Namen, den Sie auch in sechs Monaten noch verstehen, etwa „Homepage“.
3. Kopieren Sie den geheimen Schlüssel aus dem Bereich, der sich öffnet. Er wird nur einmal angezeigt, da der Server nur einen Hash davon speichert. Die Liste zeigt danach die letzten Zeichen.

Wenn Sie einen Schlüssel verlieren, widerrufen Sie ihn und erstellen Sie einen neuen. Der Widerruf gilt sofort und kann nicht rückgängig gemacht werden.

2. Bei jeder Anfrage mitsenden

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

Die meisten Dashboards bieten nur ein Authorization-Feld, deshalb funktioniert auch die Bearer-Form. Wenn Sie beides senden, hat der eigene Header Vorrang.

3. Die Route wählen

Alle sechs sind GET-Routen unter /api/integration/v1.

Route	Antwort
/server	Die Installation: Name, Version, Prozessstart und die unterstützte API-Version
/statistics	Filme, Serien, Folgen, Dateien und Bytes auf dem Datenträger
/libraries	Jede Mediathek mit Dateianzahl und dem Zeitpunkt ihres letzten Scans
/sessions	Was gerade läuft: Titel, Position, Laufzeit und ob transkodiert wird
/metrics	Dieselben Zählwerte im Prometheus-Textformat
/history	Was abgespielt wurde, neueste zuerst, seitenweise mit limit und offset

/statistics ist die Kachel, die die meisten haben möchten:

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

• /libraries zählt Dateien, daher erscheint eine Mediathek ohne Dateien erst mit dem ersten Scan, der etwas findet.
• /sessions gibt in refreshAfterSeconds an, wie oft Sie abfragen sollten. Halten Sie sich daran: Ein Dashboard, das jede Sekunde abfragt, belastet den Server unnötig und kann die Wiedergabe für alle anderen verlangsamen.
• /history gibt an, was wann abgespielt wurde, aber nie, wer es angefordert hat.

Die Referenz Feld für Feld finden Sie unter quven.tv/api/integration/v1, daneben das OpenAPI-Dokument für generierte Clients. Beide werden aus den Routen des Servers selbst erzeugt.

4. Mit Prometheus abfragen

/metrics ermöglicht es Grafana, den Server ohne Exporter auszulesen:

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. Mit ETag ressourcenschonend abfragen

Jede Leseanfrage liefert ein ETag. Senden Sie es als If-None-Match zurück, antwortet ein unveränderter Server mit 304 ohne Body. Über ein Relay entscheidet das darüber, ob eine Abfrage einen Round Trip kostet oder eine komplette Mediathekliste. Die Ausnahme ist /sessions: Die Antwort enthält den Zeitpunkt ihrer Erstellung und unterscheidet sich daher jedes Mal.

6. Im Browser ausprobieren

Die Referenzseite führt diese Abfragen gegen Ihren eigenen Server aus: Geben Sie in der Leiste oben die Adresse und einen Schlüssel ein und klicken Sie auf Send. Die Anfrage geht von Ihrem Browser an Ihren Server und nirgendwo sonst hin. Drei Dinge verhindern sie, und die Seite nennt, welches davon sie erkennen kann:

• Ein Server mit einfachem http, von dieser Seite aus aufgerufen, sofern er nicht auf diesem Rechner läuft.
• Eine Adresse, die Ihr Browser nicht erreichen kann.
• Ein Server, der älter als die Konsole ist und diese Seite noch nicht zulässt.

Der curl-Button deckt alle drei Fälle ab.

Prüfen, ob der Server läuft

GET /health/live antwortet mit 200 und dem Wort Healthy und benötigt keinen Schlüssel, sodass ein Monitoring-Dienst den Endpunkt abfragen kann, ohne ein Geheimnis zu speichern. /health/ready erfordert eine Authentifizierung und ist dafür nicht vorgesehen. Die Laufzeit selbst steht in startedUtc unter /server und in quven_server_start_time_seconds in den Metriken.

Was sie nie zurückgibt

• Ordnerpfade. /libraries wird aus der Katalogstatistik erstellt und liest nie die Mediathekkonfiguration, daher kann ein Pfad wie /mnt/tank/media/films nicht nach außen gelangen.
• Identität der Zuschauer. /sessions zeigt, dass etwas wiedergegeben wird und was, aber nie, wer es ansieht.

Limits und Versionierung

• Ein Schlüssel darf 120 Anfragen pro Minute stellen. Gezählt wird pro Schlüssel, sodass eine falsch konfigurierte Integration nur ihr eigenes Kontingent aufbraucht und die anderen nicht beeinträchtigt.
• Ein Server verwaltet bis zu 25 aktive Schlüssel. Wenn Sie diese Grenze erreichen, haben Sie mit ziemlicher Sicherheit vergessen, etwas zu widerrufen.
• Die Routen liegen unter /api/integration/v1, getrennt von denen der Quven-Apps, und dieser Pfad bleibt über Client-Versionen hinweg stabil.
• Ein Server, der älter als die API ist, antwortet überall mit 404. Fragen Sie zuerst /server ab und lesen Sie dort apiVersion.

Wenn ein Schlüssel offengelegt wird

Wer ihn besitzt, kann Ihren Katalog lesen und sehen, was gerade wiedergegeben wird. Er kann jedoch weder einen Scan starten noch eine Mediathek ändern, eine Datei anfassen oder einen weiteren Schlüssel ausstellen, denn die Schlüsselverwaltung erfordert einen Login als Eigentümer. Mit dem Widerruf des ursprünglichen Schlüssels ist der Zugriff beendet.

Diese Grenze ist der Grund für die Form der API: Einem Dashboard das Token Ihres Kontos zu überlassen, wäre einfacher umzusetzen gewesen und weit weniger sicher.