Observabilidad: métricas, salud y logs

Solo podés operar lo que podés ver

StreamHub está hecho para ser observado. De fábrica expone métricas Prometheus, una sonda de salud, un endpoint de stats del servidor y un almacén de logs estructurado — las cuatro cosas que necesitás para operar un servidor de medios sin adivinar.

Prometheus en /metrics

El core expone métricas de prom-client en la ruta raíz /metrics (fuera del prefijo /api/v1, según la convención de Prometheus). Es pública por defecto, o podés exigir un METRICS_TOKEN. Cada métrica lleva el prefijo streamhub_:

• streamhub_active_streams — streams en vivo, por app.
• streamhub_stream_viewers — último conteo de espectadores observado por stream.
• streamhub_vods / streamhub_vods_generated_total — filas VOD por estado y totales.
• streamhub_upload_queue_depth — VODs pendientes de subida, por app.
• streamhub_s3_uploads_total / streamhub_s3_errors_total — salud del almacenamiento.
• streamhub_recording_failures_total — fallos, por motivo.
• streamhub_tenant_quota / streamhub_tenant_usage — uso contra límites.
• streamhub_http_request_duration_seconds — histograma de latencia de peticiones.

LiveKit también expone sus propias métricas nativas — hacé scrape de ambos para el panorama completo.

Un job de scrape de Prometheus

scrape_configs:
  - job_name: streamhub
    metrics_path: /metrics
    static_configs:
      - targets: ['media.example.com']

Desde ahí, los dashboards de Grafana y las reglas de alertmanager van aguas abajo: alertá si streamhub_upload_queue_depth sube, si streamhub_recording_failures_total crece, o si streamhub_active_streams alcanza tu línea de capacidad.

Salud y stats

• GET /api/v1/health es una sonda de liveness pública que devuelve { status, up, version, uptimeSeconds } — apuntá acá tu balanceador o monitor de uptime.
• GET /api/v1/stats (autenticado) devuelve una foto rica: carga de CPU, memoria, disco, si LiveKit / egress / ingress están alcanzables, y conteos de apps, salas y streams activos.

curl -s $BASE/health
curl -s $BASE/stats -H "Authorization: Bearer $TOKEN"

Logs que podés consultar

Más allá de las métricas, StreamHub mantiene un almacén de logs estructurado y consultable, y el CLI streamhub logs sigue los logs de compose y puede guardarlos para un paquete de soporte. Entre métricas para tendencias, stats para una foto puntual y logs para el detalle, podés responder "¿está sano, y si no, por qué?" sin entrar por SSH a ciegas.