.. _API_OBS: API pública de observabilidad ============================= La API pública de observabilidad de WOCU-Monitoring permite a sistemas y herramientas externas acceder a los datos de observabilidad de un Reino, incluyendo métricas, eventos de monitorización, anomalías detectadas, predicciones de comportamiento (*forecasting*), estado del hardware y tráfico de red. Son 20 operaciones de solo lectura bajo ``/api/v1/observability/realm//``. **Principales funcionalidades** **Integrar WOCU-Monitoring con otras herramientas**: permite llevar los datos de observabilidad a cuadros de mando, gestores de APIs o plataformas de observabilidad externas sin entrar en la interfaz. **Automatizar consultas**: evita recoger a mano, pestaña por pestaña, lo que muestran los paneles de Observabilidad. **Integrar sin probar a ciegas**: con la referencia completa, quien integra sabe de antemano qué campos recibirá y cómo tratar cada error. ¿Cómo funciona? --------------- **De dónde obtiene la información** De los datos que WOCU-Monitoring ya guarda del reino. Anomalías, forecasting y estado del hardware se leen del Elasticsearch del reino; métricas y eventos, de su almacén de monitorización; el tráfico de red, de los datos de flujos. **Qué procesa WOCU-Monitoring** Comprueba que el usuario tiene acceso al reino, valida los parámetros y calcula el resultado: por ejemplo, cuenta los hosts con anomalías o agrupa el tráfico por puerto. **Qué resultado genera** Una respuesta en JSON, Métricas y eventos pueden pedirse también en formato OpenTelemetry (OTLP). **Actualización** Cada respuesta se calcula en el momento de la petición. Los paneles indican en el campo ``as_of`` el instante al que corresponde. **Dependencias** Anomalías y forecasting dependen del trabajo de Machine Learning de Elastic del reino. El tráfico de red depende de que el reino tenga recogida de flujos. ¿Cómo se utiliza? ----------------- 1. Disponer de un usuario de WOCU-Monitoring con acceso al reino que se quiere consultar. 2. Elegir cómo autenticarse: usuario y contraseña (HTTP Basic), token (``Authorization: Token ``) o JWT (``Authorization: Bearer ``). 3. Consultar la referencia y elegir la operación: en la página **Documentación API pública** del manual o en el Swagger de la instalación (``/api-docs/``). 4. Lanzar una petición ``GET`` a ``/api/v1/observability/realm///`` con los parámetros necesarios. 5. Leer la respuesta. Si la operación pagina, repetir la petición con el ``next_offset`` o el ``next_cursor`` recibido hasta que no queden más datos. **Ejemplo: hosts con anomalías en los últimos 30 días** Petición: .. code-block:: bash curl -u : \ "/api/v1/observability/realm//anomalies/summary/" Respuesta: .. code-block:: json { "realm": "demo-realm", "as_of": "2026-01-31T12:00:00Z", "time_from": "2026-01-01T12:00:00Z", "time_to": "2026-01-31T12:00:00Z", "hosts": 12, "window_days": 30, "exact": true } Opciones disponibles -------------------- Operaciones ^^^^^^^^^^^ .. list-table:: :header-rows: 1 :widths: 30 70 * - Opción - Descripción * - ``metrics/`` - Devuelve las series de métricas de los hosts del reino, con la función de agregación (``avg``, ``min``, ``max``, ``sum`` o ``count``) y el intervalo que se pidan. Solo sirve las métricas de la lista permitida de la instalación. * - ``events/`` - Devuelve los eventos de monitorización (alertas, notificaciones, flapping) con un conjunto fijo de campos y una severidad normalizada. * - ``hardware-health/summary/`` - Indica cuántos hosts tienen el hardware en estado crítico, en aviso, desconocido, sin datos suficientes o con la monitorización interrumpida. * - ``anomalies/…`` (6 operaciones) - Describen los hosts con anomalías detectadas por Machine Learning: resumen, tendencia semanal, reparto por severidad, evolución diaria, reparto por recurso (CPU o memoria) y listado de hosts. * - ``forecasting/…`` (4 operaciones) - Dan la previsión a 24 horas de CPU y memoria: ejecuciones disponibles, resumen de los hosts que cruzarán sus umbrales, serie de un host y catálogo de métricas. * - ``network-traffic/…`` (7 operaciones) - Miden el volumen de tráfico observado en los flujos: resumen, puertos de servicio principales, protocolos, evolución, cambios respecto al periodo anterior, calidad del dato y destinos principales. Parámetros ^^^^^^^^^^ .. list-table:: :header-rows: 1 :widths: 35 65 * - Opción - Descripción * - ``time_from``, ``time_to`` - Acotan el rango de métricas y eventos, en formato ``DD/MM/AAAA HH:MM:SS`` y hora local de la instalación. Sin ellos se consulta la última hora. * - ``from``, ``to`` - Acotan el rango de los paneles que lo admiten, en ISO 8601 (UTC si no lleva desplazamiento) o milisegundos epoch. ``from`` se incluye y ``to`` no. Por defecto son 30 días en anomalías y tráfico de red, y 24 horas en la serie de forecasting. * - ``as_of`` - Fija el instante al que se refiere la respuesta en el resumen y la tendencia de anomalías y en forecasting. Por defecto es el momento de la petición. * - ``size``, ``offset`` - Paginan las métricas: cuántos hosts trae cada página (10 por defecto) y desde cuál continuar. En eventos, ``size`` es el máximo de eventos devueltos. * - ``limit``, ``cursor`` - Paginan el listado de hosts con anomalías y las ejecuciones de forecasting (100 filas por defecto, 1.000 como máximo). En los demás listados, ``limit`` indica cuántas filas principales devolver. * - ``sort`` - Ordena los eventos por fecha o por estado. Por defecto, los más recientes primero. * - ``format`` - Solo en métricas y eventos: ``json`` (por defecto), ``otlp`` u ``otlp-ndjson`` para recibir el dato en formato OpenTelemetry. * - ``monitoring_gap_minutes`` - En el estado del hardware, fija los minutos sin muestras a partir de los cuales un host cuenta como interrumpido: 0, 15, 30, 60 o 120 (15 por defecto). * - ``transport``, ``service_port``, ``exporter_address`` - Acotan el tráfico de red a un protocolo (``tcp`` o ``udp``), a un puerto o a un máximo de 20 exportadores. Resultado --------- **Dónde se consulta** En la respuesta de cada petición, en JSON. **Qué información aparece** La referencia enumera, para cada operación, todos los campos con su tipo y significado, y un ejemplo. Los paneles comparten cuatro campos de cabecera: ``realm``, ``as_of``, ``time_from`` y ``time_to``. **Cómo interpretarlo** El código ``200`` trae los datos. El resto indica el motivo del fallo: .. list-table:: :header-rows: 1 :widths: 15 85 * - Código - Significado * - ``400`` - Un parámetro no es válido; la respuesta dice cuál. * - ``401`` - Las credenciales no son válidas. * - ``403`` - El usuario no tiene acceso al reino. * - ``404`` - El reino o el recurso pedido no existe. * - ``429`` - El cliente ha superado su límite de peticiones. * - ``502``, ``504`` - Falló la consulta de los datos o se agotó el tiempo. El dato es desconocido, no vacío. **Qué hacer después** Continuar la paginación si quedan datos, o cargar el resultado en la herramienta externa. Consideraciones y limitaciones ------------------------------ **Solo lectura** Todas las operaciones son ``GET`` y no modifican nada. **Permisos** El usuario necesita acceso al reino. Si la instalación usa reglas de acceso por ruta, también necesita tener permitida la ruta. **Datos en Elasticsearch** Anomalías, forecasting y estado del hardware exigen que el reino guarde sus datos en Elasticsearch; en otro caso responden ``400``. **Recogida de flujos** El tráfico de red exige que el reino tenga recogida de flujos; en otro caso responde ``404``. **Rango máximo** Una consulta abarca 31 días como máximo en métricas, eventos y tráfico de red. En métricas y eventos ese máximo es un ajuste de la instalación. **Alcance de forecasting** Cubre seis métricas de CPU y memoria, con un horizonte de 24 horas en tramos de 15 minutos. **Límites de peticiones** Solo se aplican a los clientes que tienen un registro de límites. **Volumen de tráfico** Son bytes observados en los flujos, sin normalizar el muestreo ni eliminar duplicados. **Nombres de campos** Algunos campos de respuesta tienen el nombre en español (``afectados``, ``desconocidos``, ``Dispositivo``, ``Nivel``); la referencia los explica en inglés. **Formato de los errores** No es uniforme: ``401`` y ``403`` devuelven un mensaje de texto y el resto, JSON.