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/<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_ofel 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 <clave>) o JWT (Authorization: Bearer <JWT>).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
GETa/api/v1/observability/realm/<realm>/<operación>/con los parámetros necesarios.5. Leer la respuesta. Si la operación pagina, repetir la petición con el
next_offseto elnext_cursorrecibido hasta que no queden más datos.
Ejemplo: hosts con anomalías en los últimos 30 días
Petición:
curl -u <usuario>:<contraseña> \ "<dirección-del-aggregator>/api/v1/observability/realm/<realm>/anomalies/summary/"
Respuesta:
{ "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
Opción |
Descripción |
|---|---|
|
Devuelve las series de métricas de los hosts del reino, con
la función de agregación ( |
|
Devuelve los eventos de monitorización (alertas, notificaciones, flapping) con un conjunto fijo de campos y una severidad normalizada. |
|
Indica cuántos hosts tienen el hardware en estado crítico, en aviso, desconocido, sin datos suficientes o con la monitorización interrumpida. |
|
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. |
|
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. |
|
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
Opción |
Descripción |
|---|---|
|
Acotan el rango de métricas y eventos, en formato
|
|
Acotan el rango de los paneles que lo admiten, en
ISO 8601 (UTC si no lleva desplazamiento) o milisegundos
epoch. Por defecto son 30 días en anomalías y tráfico de red, y 24 horas en la serie de forecasting. |
|
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. |
|
Paginan las métricas: cuántos hosts trae cada página (10 por defecto) y desde cuál continuar. En eventos, |
|
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, |
|
Ordena los eventos por fecha o por estado. Por defecto, los más recientes primero. |
|
Solo en métricas y eventos: |
|
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). |
|
Acotan el tráfico de red a un protocolo ( |
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_fromytime_to.
Cómo interpretarlo
El código
200trae los datos.El resto indica el motivo del fallo:
Código |
Significado |
|---|---|
|
Un parámetro no es válido; la respuesta dice cuál. |
|
Las credenciales no son válidas. |
|
El usuario no tiene acceso al reino. |
|
El reino o el recurso pedido no existe. |
|
El cliente ha superado su límite de peticiones. |
|
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
GETy 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:
401y403devuelven un mensaje de texto y el resto, JSON.