Monitorizar PrintStash con Prometheus y Grafana

PrintStash expone métricas de Prometheus en /metrics, dentro del servicio de la API. Añádelo a un stack de monitorización que ya tengas cuando quieras tendencias y alertas fuera de la aplicación.

Qué te da /metrics

El endpoint exporta cuatro familias de métricas útiles:

• printstash_http_request_duration_seconds registra la latencia por método, plantilla de ruta y estado. Las plantillas de ruta evitan que los IDs de los modelos generen etiquetas sin límite.
• printstash_ingestion_jobs_total cuenta los trabajos de ingesta completados y fallidos.
• printstash_printer_status cuenta las impresoras configuradas por proveedor y estado general en el momento de la lectura.
• printstash_app_info informa de los datos de compilación.

Las métricas son locales al proceso y encajan con el despliegue normal de un solo proceso. No añadas varios workers de Uvicorn esperando que los contadores se agreguen solos.

Añade el trabajo de scrape

Para una API accesible como printstash-api:8000:

scrape_configs:
  - job_name: printstash
    static_configs:
      - targets: ["printstash-api:8000"]

El endpoint está abierto por defecto. Define VAULT_METRICS_TOKEN si la red de monitorización no es de plena confianza, reinicia la API y añade el mismo token a Prometheus:

scrape_configs:
  - job_name: printstash
    authorization:
      type: Bearer
      credentials: "<metrics-token>"
    static_configs:
      - targets: ["printstash-api:8000"]

Usa un nombre de servicio de Docker cuando Prometheus comparta la red. Usa una dirección de la LAN solo si el puerto de la API es accesible a propósito desde el equipo donde corre Prometheus.

Alertas con las que empezar

• Ningún scrape correcto durante cinco minutos.
• Un aumento sostenido de trabajos de ingesta fallidos.
• Una impresora que sigue fuera de línea fuera de una ventana de mantenimiento.
• Un percentil alto de latencia de la API sobre un periodo útil, no una petición lenta suelta.

Las alertas de impresora que salen de Prometheus son independientes de los canales de notificación de PrintStash. Usa el sistema que ya se encargue del enrutado, los silencios y el ruido de las guardias en tu homelab.

El endpoint de salud es la otra mitad

/api/v1/health es una sonda de actividad mínima (nombre, versión, estado). Usa /api/v1/health/details para la sonda operativa: estado de la base de datos, el almacenamiento, las copias de seguridad, los proveedores de impresora, la ingesta y la biblioteca compartida.

Las integraciones opcionales se degradan sin arrastrar al resto. Por ejemplo, una conexión con Spoolman que no está disponible se ve, pero no hace que todo el servicio pase a estar en mal estado.

Apunta Uptime Kuma o un balanceador de carga a health. Apunta Prometheus a metrics. Usa el registro de auditoría de la aplicación cuando lo que necesites saber sea quién cambió el estado, y no cómo se comportó el servicio a lo largo del tiempo.

Las alertas de impresión a nivel de aplicación se configuran por separado en la guía de notificaciones. Si Prometheus llega a PrintStash cruzando fronteras de red, revisa el modelo de red de confianza antes de exponer el puerto de la API.