Supervisa tu servidor multimedia con Prometheus y Grafana

Quven tiene una pequeña API de solo lectura para paneles domésticos. Creas una clave desde los ajustes del servidor, la envías en una cabecera y lees lo que el servidor guarda y lo que está reproduciendo. La clave no puede cambiar nada: así están construidas las rutas, no es una política.

1. Crea una clave

1. Abre Settings, ve a Server y busca la tarjeta Integration keys.
2. Ponle a la clave un nombre que sigas entendiendo dentro de seis meses, como «Homepage».
3. Copia el secreto del panel que se abre. Aparece una sola vez, porque el servidor solo conserva un hash. Después, la lista muestra los últimos caracteres.

Si pierdes una clave, revócala y crea otra. La revocación es inmediata y no se puede deshacer.

2. Envíala con cada petición

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 mayoría de los paneles solo ofrecen un campo Authorization, y por eso también funciona la forma bearer. Si envías las dos, gana la cabecera dedicada.

3. Elige la ruta

Las seis son GET, bajo /api/integration/v1.

Ruta	Respuesta
/server	La instalación: nombre, versión, inicio del proceso y versión de API que habla
/statistics	Películas, series, episodios, archivos y bytes en disco
/libraries	Cada biblioteca con su número de archivos y la hora de su último análisis
/sessions	Lo que se reproduce: título, posición, duración y si transcodifica
/metrics	Los mismos recuentos en texto de Prometheus
/history	Lo que se reprodujo, lo más reciente primero, paginado con limit y offset

/statistics es el mosaico que más gente quiere:

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

• /libraries cuenta archivos, así que una biblioteca que no tiene ninguno aparece con el primer análisis que encuentre algo.
• /sessions te dice cada cuánto preguntar en refreshAfterSeconds. Respétalo: un panel que consulta cada segundo carga el servidor para nada y puede ralentizar la reproducción de todos los demás.
• /history dice qué se reprodujo y cuándo, nunca quién lo pidió.

La referencia campo por campo está en quven.tv/api/integration/v1, con el documento OpenAPI al lado para los clientes generados. Ambos se construyen a partir de las rutas del propio servidor.

4. Consúltala con Prometheus

/metrics permite que Grafana lea el servidor sin un exportador:

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. Consulta con poco coste usando ETag

Cada lectura lleva un ETag. Devuélvelo como If-None-Match y un servidor que no ha cambiado responde 304 sin cuerpo, lo que a través de un relé marca la diferencia entre una consulta que cuesta un viaje de ida y vuelta y otra que cuesta el listado de una biblioteca. La excepción es /sessions: su respuesta lleva el instante en que se tomó, así que difiere cada vez.

6. Pruébala en el navegador

La página de referencia ejecuta estas lecturas contra tu propio servidor: escribe la dirección y una clave en la barra de arriba y pulsa Send. La petición va de tu navegador a tu servidor y a ningún otro sitio. Tres cosas la detienen, y la página dice cuáles puede:

• Un servidor en http sin cifrar, al que se llega desde esa página, salvo que esté en esta misma máquina.
• Una dirección a la que tu navegador no puede llegar.
• Un servidor más antiguo que la consola, que todavía no admite esa página.

El botón de curl cubre los tres.

Comprueba que el servidor está activo

GET /health/live responde 200 con la palabra Healthy y no necesita clave, así que un monitor puede consultarlo sin guardar un secreto. /health/ready exige autenticación y no está pensado para eso. El tiempo en marcha es startedUtc en /server y quven_server_start_time_seconds en las métricas.

Lo que nunca devuelve

• Rutas de carpetas. /libraries se construye con las estadísticas del catálogo y nunca lee la configuración de las bibliotecas, así que una ruta como /mnt/tank/media/films no puede filtrarse.
• La identidad de quien ve. /sessions muestra que algo se reproduce y qué es, nunca quién lo mira.

Límites y versiones

• Una clave tiene permitidas 120 peticiones por minuto. El recuento es por clave, así que una integración mal configurada gasta su propio presupuesto y no afecta a las demás.
• Un servidor guarda 25 claves activas. Si llegas a ese tope, es casi seguro que has olvidado revocar algo.
• Las rutas viven bajo /api/integration/v1, aparte de las que usan las aplicaciones de Quven, y esta ruta se mantiene estable entre versiones del cliente.
• Un servidor más antiguo que la API responde 404 a todo. Consulta primero /server y lee su apiVersion.

Si una clave se filtra

Quien la tenga puede leer tu catálogo y ver qué se reproduce. No puede iniciar un análisis, cambiar una biblioteca, tocar un archivo ni crear otra clave, porque la gestión de claves queda detrás de un inicio de sesión de propietario. Revocar la clave original pone fin al acceso.

Esa frontera es la razón por la que la API tiene esta forma: darle a un panel el token de tu cuenta habría sido más sencillo de construir y mucho menos seguro.