Skip to content

API

control.plane.api

Sapsan expone el estado del servidor por HTTP. La API es compatible en formato con la Flussonic Streamer API v3, así que las integraciones existentes siguen funcionando.

Acceso

El acceso a la API está protegido por un usuario y una contraseña en la sección api_auth:

api_auth:
  login: admin
  password: secret

Endpoints

El prefijo base es /streamer/api/v3:

Método y ruta Qué devuelve
GET /streamer/api/v3/streams lista de streams y su estado
GET /streamer/api/v3/config configuración actual del servidor
GET /streamer/api/v3/dvrs lista de almacenamientos DVR
GET /streamer/api/v3/dvrs/{name} estado de un DVR concreto
GET /streamer/api/v3/rproxy estado de la pasarela Peeklio y de los agentes
GET /streamer/api/v3/monitoring/readiness sonda de readiness para orquestadores

API nativa v4

La API nativa, aún en evolución, vive bajo el prefijo /streamer/api-v4:

Ruta Qué devuelve
GET /listeners lista de listeners
GET /streams, GET /streams/{name} streams y su estado
GET /streams/stats, GET /streams-stats estadísticas de streams
GET /sessions/stats estadísticas de sesiones
GET /live-metrics, GET /sessions-metrics métricas de live y de sesiones
GET /dvr, GET /dvr/catalog, GET /dvr/metrics estado del almacenamiento y del catálogo DVR
POST /dvr/rebuild-index, GET (estado), DELETE (detener) reconstrucción del catálogo desde los discos
POST /dvr/cleanup, GET /dvr/cleanup iniciar la limpieza del archivo / estado
GET /runtime/metrics métricas del proceso en formato Prometheus
GET /auth estado de la autorización
GET /license/status estado de la licencia
GET /rproxy/streampoint-agents agentes de la pasarela Peeklio

Note

TODO: ejemplos de respuestas, gestión de streams por API (cuando existan operaciones de escritura).

Qué viene después

Acceso al Admin API

El Admin API está protegido por una sección aparte api_auth — véase Admin API.

Salud del servidor

  • Sonda de readiness: GET /streamer/api-v3/monitoring/readiness — para Kubernetes y balanceadores.
  • Estado de los streams: GET /streamer/api-v3/streams.

Estadísticas del stream en el Admin API

La lista de streams

GET /streamer/api-v4/streams/stats devuelve un elemento por stream — la página de streams de la UI vive de esta lista, y también es lo correcto para sondearla desde scripts.

Campo Qué significa Cómo usarlo
status, status_since el estado del stream y el momento en que entró en él fuera de running durante más de N minutos — alerta
bitrate_kbit el bitrate de medios medido de la entrada activa, por los timestamps de los fotogramas caído visiblemente por debajo del nominal — la fuente se degradó. Esto no es el throughput de red: un archivo puede leerse más rápido que el tiempo real
source.url la entrada que está reproduciendo realmente difiere de la primera del config — el stream vive en una reserva
inputs[] el estado de runtime de cada entrada configurada: url, status, antigüedad de la comprobación checked_ago_ms, bitrate, texto del error véase más abajo
dvr.from, dvr.to la ventana del archivo en este servidor to se retrasa respecto al tiempo actual — la grabación se detuvo; from dejó de avanzar — la limpieza no funciona, adelante un desbordamiento de disco
dvr.recorded_hours, dvr.bytes, dvr.periods los totales del archivo: cuántas horas están grabadas, cuánto espacio en disco ocupa el archivo y de cuántos tramos continuos consta; se actualiza una vez por minuto, precisión de una hora recorded_hours notablemente menor que la anchura de la ventana to - from — el archivo tiene huecos; bytes — el espacio que el stream ocupa en el servidor
bytes_in, bytes_out contadores acumulados de bytes desde el arranque del stream para velocidades e historia use el servidor Prometheus integrado o Retroview: la instantánea se pone a cero con un reinicio

Estados de los elementos de inputs[]:

  • active — reproduciendo ahora mismo;
  • ok — una reserva, viva según la última comprobación;
  • error — una reserva con un problema registrado (el texto, en error);
  • unchecked — una reserva que aún no se ha comprobado nunca.

Esto responde a la pregunta principal del failover: «¿conmutaremos de verdad cuando caiga la principal?». Las reservas se comprueban periódicamente (recheck_secondary_inputs_interval, véanse las fuentes de reserva); alerte sobre error, sobre unchecked y sobre un checked_ago_ms demasiado antiguo — una reserva sin comprobar no puede considerarse operativa.

Un solo stream

GET /streamer/api-v4/streams/stats/{name} añade a esos mismos campos secciones de diagnóstico — no están en la lista para que la lista siga siendo barata.

La sección input — contadores de la entrada actual:

Campo Para qué
bytes, frames, bitrate_kbit si la entrada trae datos y a qué velocidad
retries reconexiones a la fuente: crece — la fuente o la red son inestables
input_switches conmutaciones entre entradas: crece — la entrada se cae y se recupera; investigue la principal
errors el contador agregado de errores de entrada: crece — hay un problema; la causa, en los contadores extendidos o en Retroview
num_sec_on_primary_input, num_sec_on_secondary_input segundos vividos en la principal y en la reserva: una proporción notable en la reserva — la entrada principal es sistemáticamente mala
num_sec_no_data segundos sin datos en absoluto
errors_lost_packets, errors_connection_closed, errors_http_request_error, … desglose de errores por causa — solo con la opción de contadores extendidos

La sección dvr en la respuesta individual se amplía con:

Campo Para qué
write.segments_written, write.segments_failed, write.segments_skipped contadores de escritura de fragmentos: segments_failed crece — el archivo está perdiendo datos ahora mismo, compruebe el disco
write.segments_written_slow / _delayed / _collapsed, write.segments_discontinuity perfilado de la escritura — solo con la opción de contadores extendidos

Note

La instantánea del Admin API se pone a cero cuando el servidor se reinicia. Responde a «qué está pasando ahora», pero no sirve ni para conciliar la factura ni para analizar el incidente de ayer — para eso está Retroview.