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_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 <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 GET a /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_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:

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

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

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:

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.