Correlación de eventos
¿QUÉ ES?
La correlación de eventos muestra en un único lugar qué eventos del perímetro observado están relacionados entre sí y por qué. Está disponible en la pestaña Observability de un Reino, en la sección Event Correlation.
¿PARA QUÉ SIRVE?
Los eventos de monitorización, syslog, traps SNMP, métricas, logs de los agentes y trazas fallidas se consultan habitualmente en lugares distintos. Cuando algo falla, resulta difícil saber cuáles pertenecen al mismo problema. Esta vista agrupa los eventos relacionados, indica el motivo de cada grupo y aporta el contexto necesario para entenderlo.
Resulta útil cuando se produce un incidente que afecta a varios hosts y se quiere saber si tienen un origen común, o para revisar de un vistazo qué ha ocurrido en un periodo. Evita tener que cruzar manualmente las distintas fuentes de eventos y deducir a mano qué hosts dependen unos de otros o comparten red.
¿CÓMO FUNCIONA?
El análisis se ejecuta únicamente cuando el usuario lo solicita. No se ejecuta en segundo plano ni periódicamente, y su resultado no se almacena como informe.
Origen de la información
El análisis lee los eventos de seis fuentes:
Monitorización: problemas confirmados de hosts y servicios.
Traps: traps SNMP con severidad warning o critical.
Métricas: métricas en estado warning o critical. Las métricas del chequeo del propio host se presentan como eventos del host, sin servicio.
Syslog: líneas de log, utilizadas únicamente como contexto.
Trazas fallidas (
otel_traces): spans con error de wocu-otel. Un fallo suele marcar varios spans de la misma traza, por lo que se muestra un solo evento por traza (el span de entrada, servidor o consumidor, y si no lo hay, el primer span con error). Su severidad es siemprewarning.Logs de agentes (
otel_logs): líneas de log recogidas por wocu-otel, utilizadas únicamente como contexto, igual que syslog. Su severidad sigue la escala de OpenTelemetry: 17 o más escritical, de 13 a 16 eswarningy el resto esinfo.
Las métricas de wocu-otel no se leen: sus superaciones de umbral ya llegan como alertas de monitorización.
La jerarquía de hosts (padres), la red de cada host y los grupos de hosts del Reino aportan contexto a los grupos. Los textos de syslog, de traps, de trazas y de logs de agentes se enmascaran antes de mostrarse. El enmascarado se basa en patrones conocidos y no detecta todos los secretos.
Los datos de wocu-otel se leen de los índices fijos logs-wocu.otel-* y
traces-wocu.otel-*, filtrando por el Reino (campo wocu.realm). El host
de cada documento se asocia por nombre exacto (host.name, distinguiendo
mayúsculas) con un host del Reino; los documentos que no corresponden a ningún
host conocido se descartan y no cuentan como eventos.
Syslog y los logs de agentes se utilizan solo como contexto y nunca originan un análisis por sí solos:
Solo se leen las líneas de los hosts que ya tienen algún evento en otra fuente, y solo las más próximas a esos eventos: desde 15 minutos antes del primer problema del host hasta 5 minutos después del último.
Se leen como máximo las 20 líneas más recientes de cada host.
Las líneas sin severidad se tratan como
info. Las de syslog que sí la traen la conservan: las severidades 0 a 3 soncritical, la 4 eswarningy el resto soninfo. Esta correspondencia se aplica solo a syslog; los logs de agentes siguen la escala de OpenTelemetry descrita arriba (17 o más escritical, de 13 a 16 eswarningy el resto esinfo).Una línea de syslog o de un agente nunca crea un grupo ni un host afectado, y nunca modifica el inicio ni el fin de un grupo. Si no hay ningún host afectado, no se consultan y esa ausencia de hosts no las marca como no disponibles. Pueden indicarse como no disponibles aunque no haya hosts afectados, si el Reino no tiene backend, si no se puede crear el cliente de lectura o si se agota el tiempo máximo del análisis.
Los logs de agentes excluyen los documentos de inventario del agente. Como un host puede enviar a WOCU por syslog los mismos ficheros que lee el agente, se descarta la línea del agente cuando el mismo host tiene una línea de syslog en el mismo análisis cuyo mensaje está contenido en el suyo y que dista menos de 5 segundos.
Qué procesa WOCU
Cada evento pertenece exactamente a un grupo. Las reglas se aplican en este orden y la primera que coincide decide el grupo:
Dependencia común: el host depende, directa o indirectamente, de un host superior de la jerarquía que tiene un problema: tiene eventos en la ventana o, en el momento de ejecutar el análisis, está caído o inalcanzable (se usa el estado leído al ejecutar, no el que tenía durante la ventana). Si varios hosts superiores cumplen, se toma el más alto. El grupo toma el nombre de ese host, por ejemplo “Dependencia común: R1”.
Misma subred: los hosts comparten red, por ejemplo “Subred 10.20.0.0/24”.
Mismo grupo de hosts: los hosts comparten un grupo de hosts, por ejemplo “Grupo de hosts Madrid”.
Host individual: en caso contrario, el host forma un grupo por sí solo.
Las reglas son fijas y deterministas: con los mismos eventos y los mismos datos de inventario y de gestión de direcciones IP, los grupos son los mismos. Esos datos se leen al ejecutar el análisis, de modo que un cambio en ellos puede cambiar los grupos y sus identificadores. No se utiliza IA para construir ni nombrar los grupos. Cada grupo indica además sus motivos: la regla aplicada, la proximidad en el tiempo de los eventos y, cuando procede, el grupo de hosts compartido (con su ubicación, si la tiene).
El inicio y el fin de un grupo, así como el motivo de concentración en el tiempo, se calculan solo con los eventos de problema (monitorización, traps, métricas y trazas fallidas). Las líneas de syslog y de logs de agentes nunca los modifican.
Qué resultado genera
El análisis genera un resumen con los contadores, los grupos y, para cada grupo, el número de eventos por fuente, una lista corta de los eventos más relevantes (en conjunto y por fuente), el contexto de su host principal y el árbol de dependencias. Para consultar todos los eventos de un grupo se utiliza la secuencia completa, que está paginada y puede filtrarse por fuente.
El resumen indica una ventana temporal explícita. La secuencia completa se solicita con esa misma ventana, de modo que el grupo se consulte en el periodo exacto en que se detectó.
Dependencias y tiempo de ejecución
El análisis depende de la monitorización, de las fuentes de eventos del Reino y de la gestión de direcciones IP, de la que obtiene la subred de los hosts (véase Direcciones no enrutables y gestión de direcciones IP). Es síncrono pero está acotado: dura como máximo unos 90 segundos. Las lecturas a monitorización y a la gestión de direcciones IP tienen tiempos máximos de espera, de modo que una dependencia lenta no bloquea el análisis. Si se agota el tiempo, el resultado es parcial pero se obtiene igualmente: las fuentes que no se llegan a leer se indican como no disponibles y las fases de contexto que se omiten se señalan como contexto parcial.
¿CÓMO SE UTILIZA?
Abra Operación > Observabilidad > Correlación de eventos en un Reino.
Seleccione un intervalo de fechas y horas. El periodo inicial comprende las últimas 24 horas. El selector también ofrece los últimos 15, 30 y 60 minutos, 6 horas y 24 horas, además de un intervalo personalizado. El intervalo no puede superar las 24 horas. No se pueden seleccionar fechas futuras.
Si desea limitar el análisis, seleccione un grupo de hosts disponible. Con Todos los grupos de hosts se analiza todo el Reino. El navegador recuerda el periodo y el grupo de hosts para cada Reino.
Pulse Ejecutar. Mientras se realiza el análisis se muestra un indicador de carga y se deshabilitan los filtros y el botón. El resultado aparece en esta página y no se guarda como informe.
Seleccione un grupo mediante su botón de selección. El primer grupo se selecciona al mostrar el resultado. Al elegir otro se actualizan sus eventos, contexto del perímetro, dependencias y motivos de correlación.
Resultados y controles
El resumen muestra Eventos analizados, Grupos relacionados y Hosts afectados. La tabla de grupos de eventos relacionados incluye el nombre, la relación y el número de hosts y eventos de cada grupo. Permite buscar y paginar. Las relaciones incluyen dependencia común, misma subred, mismo grupo de hosts y host individual.
Al situar el cursor sobre el número de la columna Hosts, o al enfocarlo con
el teclado, se muestran los nombres disponibles de los hosts del grupo. La
lista incluye hasta 20 nombres; si hay más, un indicador +N señala cuántos
no aparecen.
Cuando está disponible y es diferente del nombre técnico, el nombre visible del host se presenta con el formato nombre visible (nombre técnico). Si ambos coinciden o falta el nombre visible, se muestra el nombre técnico. Este formato se utiliza en los grupos, eventos, contexto, dependencias y destino del RCA; las consultas y los enlaces siguen utilizando el nombre técnico.
La tabla de eventos del grupo seleccionado muestra inicialmente los eventos más relevantes devueltos por el análisis. Sus columnas son hora, origen, host, servicio, severidad y texto del evento. Los enlaces de host y servicio abren las vistas correspondientes. La búsqueda admite el nombre técnico y el nombre visible del host. La paginación y el filtro de origen permiten acotar los eventos mostrados. Aplique o borre el filtro de origen mediante los controles de la tabla.
Ver secuencia completa carga todos los eventos del grupo seleccionado para la misma ventana del análisis. Esta vista utiliza paginación en el servidor y permite buscar y filtrar por origen; Volver a los eventos principales regresa a la vista inicial. La secuencia completa suele estar disponible durante 30 minutos. Si caduca, vuelva a ejecutar la correlación; consulte Caducidad de la secuencia completa para conocer las limitaciones relacionadas con la caché.
Las tarjetas situadas junto a las tablas describen el grupo seleccionado:
Contexto del perímetro resume dónde empieza el grupo y hasta dónde llega. Muestra, por este orden, la primera señal observada dentro del periodo analizado (host, hora, origen, severidad y texto), qué comparten los hosts (dependencia, subred o grupo de hosts) con cuántos de ellos están afectados sobre el total, el estado actual de los hosts del grupo, el orden en que se vieron afectados los primeros hosts, los servicios con más eventos y los detalles del host principal. De estos detalles (IP, subred de IPAM, sede, grupos de hosts y rol) solo se muestran los que tienen valor. El perímetro total puede no conocerse, por ejemplo si el inventario no está disponible; en ese caso solo se indica el número de hosts afectados. La primera señal es la primera observada, no una causa confirmada.
Dependencias de hosts muestra el host principal, sus padres y los descendientes relevantes, con sus estados. Una nota explica que la jerarquía configurada no representa enlaces físicos. La tarjeta indica si no hay datos de dependencias o si el árbol está incompleto por el límite de resultados. Cuando se dispone de permiso para la vista de árbol del host, su nombre es un enlace que abre esa vista centrada en el host seleccionado.
Motivo de la correlación muestra la relación, la concentración temporal de eventos y el grupo de hosts compartido cuando se dispone de esos motivos. Un aviso aclara que una relación observada no es una causa raíz confirmada.
RCA abre un análisis de causa raíz (Root Cause Analysis). La tarjeta indica el tipo y el nombre del destino antes de iniciar el análisis. El destino depende de la relación del grupo seleccionado:
Mismo hostgroup: el hostgroup que identifica el grupo.
Dependencia común: el host del que dependen los hosts del grupo.
Host individual: el host del grupo.
Misma subred: el host principal del grupo, ya que el RCA no admite una subred como destino.
En los análisis de host, el inicio del grupo sirve de referencia para la ventana del análisis. El RCA de hostgroup utiliza su propio contexto y ventana. El botón permanece visible, pero se deshabilita si faltan los datos de investigación o el nombre del destino, si el usuario no tiene permiso para la acción de RCA de host, si no está disponible ninguno de los dos endpoints de RCA o si el modal de análisis ya está abierto. El modal muestra el progreso, el resultado o un error; el enlace al historial de RCA requiere acceso a esa sección. La interfaz admite los temas claro y oscuro.
Mensajes y limitaciones
La página muestra el mensaje devuelto por el análisis cuando existe, incluido el mensaje de ausencia de datos cuando corresponde. Los errores de las peticiones se muestran en la página, incluidos los errores al cargar la secuencia completa. El análisis puede ser parcial si no están disponibles algunas fuentes o datos de contexto; la correlación o el host principal por sí solos no confirman la causa raíz.
CONSIDERACIONES Y LIMITACIONES
Permisos
El widget event-correlation concede acceso a los endpoints de correlación
y a la lista de grupos de hosts del Reino utilizada por el filtro. El acceso se
controla a nivel de Reino. El grupo de hosts es opcional; sin él, el análisis
abarca todo el Reino.
El botón de investigación requiere la acción de host
ai-assistant-root-cause-analysis y al menos uno de los endpoints de RCA:
ai-assistant-root-cause-analysis u observability-root-cause-analyses.
El widget de correlación no concede por sí mismo esos endpoints. El botón se
deshabilita si falta la acción, no está disponible ninguno de los endpoints o
faltan los datos de investigación.
Límites
Los resultados se resumen para que un perímetro grande siga siendo legible:
Se devuelven como máximo 20 grupos, con un máximo de 20 hosts y 20 eventos destacados cada uno (y 10 por fuente). Los grupos con relación van primero y, si hay que omitir grupos, se descartan primero los hosts individuales.
De monitorización se leen como máximo las 10000 alertas más recientes del periodo y de traps los 1000 eventos más recientes (se muestrean los más recientes); de métricas, hasta 1000 series.
De syslog y de los logs de agentes se leen como máximo las 20 líneas más recientes de cada host.
De las trazas fallidas se leen como máximo los 1000 spans con error más recientes; el total que se informa es el número de trazas distintas.
No se admiten tramos superiores a 24 horas.
Tiempo de ejecución
El análisis dura como máximo unos 90 segundos y las lecturas tienen tiempos
máximos de espera. Si se agota el tiempo, el resultado es parcial pero la
respuesta sigue siendo correcta (200). La interfaz debe permitir un
análisis largo, sin un tiempo de espera propio inferior a unos 120 segundos, y
no debe lanzar un segundo análisis mientras hay uno en curso.
Fuentes sin índice
Los índices de syslog y de traps se buscan entre los que existen en el almacén del Reino. Si el Reino no tiene ninguno de esos dos (por ejemplo, un Reino sin traps), la fuente se considera vacía, no no disponible. Lo mismo ocurre con los logs y las trazas de wocu-otel: un Reino sin datos de wocu-otel tiene esas fuentes vacías. Los índices de monitorización y de métricas se deducen de la configuración del Reino y no se comprueban antes: si uno no existe, su lectura falla y la fuente se indica como no disponible.
Direcciones no enrutables y gestión de direcciones IP
La subred de un host se obtiene de los prefijos de la gestión de direcciones IP del Reino, que se leen una sola vez por análisis. Un host con una dirección IP utilizable recibe el prefijo más específico que contiene su dirección, tenga o no la dirección un registro propio en la gestión de direcciones IP. Si dos prefijos empatan, decide el registro de la dirección. Una dirección que no está dentro de ningún prefijo no tiene subred.
Los hosts cuya dirección no es una dirección IP válida (por ejemplo, un nombre DNS) o no identifica a un único host (sin especificar, de loopback o de enlace local) no se consultan en la gestión de direcciones IP y no muestran subred. Si el listado de prefijos no se puede utilizar, se consulta la gestión de direcciones IP por cada dirección, con un máximo de 50 consultas y un tiempo total limitado. Si la gestión de direcciones IP no está disponible, o las consultas por dirección superan ese máximo o ese tiempo, los hosts sin resolver quedan sin subred, las fases de contexto que no se completan se omiten y el resultado se marca como contexto parcial; los grupos siguen siendo válidos.
Caducidad de la secuencia completa
La secuencia completa se sirve únicamente del resultado guardado del análisis,
que se conserva durante 30 minutos. Si el resultado ha caducado, o no está
disponible, se responde 410 con el mensaje
“Este análisis ha caducado. Vuelve a ejecutarlo.” y el usuario debe ejecutar el
análisis de nuevo. Un grupo que no pertenece a ese análisis sigue respondiendo
404.
El resultado guardado usa la caché compartida del entorno. En un entorno sin
caché compartida entre procesos (la caché por defecto no guarda nada), la
secuencia completa vuelve a calcular la ventana del análisis en cada petición.
Si la caché compartida está configurada pero no disponible, la secuencia completa
responde siempre 410: volver a ejecutar el análisis no lo soluciona y, si el
410 se repite justo después de ejecutar el análisis, consulte con el
administrador de la plataforma.
INFORMACIÓN RELACIONADA
Action Root Cause Analysis (RCA): análisis de causa raíz utilizado por la acción RCA.
Per-realm AI agent: agente de IA del Reino para el análisis de causa raíz.
Anexo técnico: Event correlation API, más abajo en esta página.
Anexo técnico: Event correlation API
Both endpoints are GET, require a logged-in session and are published to
the frontend in the permissions map under these keys:
Key |
Use |
|---|---|
|
Run the analysis and read the groups. |
|
Read the full sequence of one group. |
Their URLs keep the placeholders <realm_type> and <realm_name>, which
the client replaces.
The event-correlation widget also grants the existing URL that lists the
realm hostgroups, used by the hostgroup filter. It is published under the key
livestatus_assets_hosts_groups (URL name livestatus-assets-hosts-groups)
and returns the hostgroups of the realm; their name is the value of the
hostgroup parameter. Other widgets grant the same URL, so removing this
widget from a profile does not remove it for them.
The correlation widget grants no RCA endpoint. The investigate button needs
the host action ai-assistant-root-cause-analysis and either the synchronous
endpoint ai-assistant-root-cause-analysis or the collection endpoint
observability-root-cause-analyses; the interface prefers the synchronous
one. The group provides investigate with the target that matches its
relation: for same_hostgroup it holds target: hostgroup and
hostgroup_name; for the other relations it holds target: host,
host_name, host_display_name and last_state_change. The host is the
anchor of a common_dependency or single_host group, and the main host of
a same_subnet group. last_state_change is the start of the group in
epoch seconds. The interface sends these values as query parameters and in the
POST body, and for the collection endpoint it adds wait: true to the body.
Access to the RCA history is controlled separately by the widget and the RCA
endpoints.
Error bodies. Only the errors raised by the correlation views are JSON with
the shape {"error": "<text>"}, in the language of the user: 400
(parameter validation), 404, 410 and 503. Two errors do not come
from the views but from the platform and have an HTML body, not JSON:
the
400for a request without the headerX-Requested-With: XMLHttpRequest;the
403for a profile without the grant for the endpoint.
When DEBUG is false, both endpoints answer that 400 before the profile
grant is checked. The user interface sends the header on every call; any other
client has to add it.
Analyse a realm
GET on observability_event_correlation.
Parameter |
Description |
|---|---|
|
Optional. Start of the analysed window: epoch seconds, epoch
milliseconds or ISO 8601 ( |
|
Optional. End of the analysed window, same formats. Without it, the window ends now. |
|
Optional shortcut, used only when neither |
|
Optional. Name of a hostgroup of the realm. Empty means all. At most 255 characters and no control characters. |
The window must not be inverted (time_from earlier than time_to), end
more than a minute in the future or be longer than 24 hours (exactly 24 hours is
valid). Any of these, or a
bound that is not in one of the formats above, answers 400.
The analysis is bounded: Livestatus reads time out after 15 s, each IPAM read
after 5 s, the per-address IPAM lookups share a budget of 8 s and the whole run has a budget
of about 90 s. Sources that are not read in time go to unavailable_sources
and skipped context stages set partial_context; the status stays 200.
The subnet of a host comes from the IPAM prefixes of the realm, read once per
run (the ipam/subnets listing, used only when it is complete). A host with
a usable IP address gets the most specific prefix that contains its address,
whether or not the address has its own IPAM record. When two prefixes tie, the
IPAM record of the address decides. An address inside no prefix has no subnet.
A host whose address is not an IP address (a DNS name) or is unspecified
(0.0.0.0, ::), loopback or link-local has no subnet and is not looked
up. When the listing cannot be used, each address is looked up in IPAM instead
(also for the ties), with at most 50 lookups and within the 8 s budget. The
hosts left without a lookup because of the cap, the budget or an unreachable
IPAM have no subnet and set partial_context, which is also set when the
inventory is unavailable or truncated or when a later context stage is skipped.
Response:
{
"schema_version": 1,
"window": {"from": "2026-11-07T10:00:00Z", "to": "2026-11-07T10:30:00Z", "period": "30m"},
"hostgroup": "Madrid",
"summary": {"events_analyzed": 5, "events_matched": 5, "related_groups": 1, "affected_hosts": 3},
"truncated": false,
"sampled": false,
"partial_context": false,
"unavailable_sources": [],
"message": null,
"message_code": null,
"generated_at": "2026-11-07T10:30:00Z",
"expires_at": "2026-11-07T11:00:00Z",
"groups": [
{
"id": "common_dependency:R1",
"relation": "common_dependency",
"anchor": "R1",
"name": "Common dependency: Core router (R1)",
"hosts_count": 3,
"events_count": 5,
"started_at": "2026-11-07T10:02:10Z",
"ended_at": "2026-11-07T10:05:40Z",
"hosts": ["R1", "SW-01", "SW-02"],
"host_display_names": {"R1": "Core router", "SW-01": "Switch 01"},
"main_host": "R1",
"events_by_source": {"monitoring": 2, "syslog": 1, "traps": 1, "metrics": 1,
"otel_logs": 0, "otel_traces": 0},
"top_events": [
{"time": "2026-11-07T10:02:10Z", "source": "monitoring", "host": "R1",
"text": "Connection timed out", "severity": "critical",
"state": "down", "object": "host", "service": null},
{"time": "2026-11-07T10:02:50Z", "source": "monitoring", "host": "SW-02",
"text": "PING WARNING - rta 620ms", "severity": "warning",
"state": "warning", "object": "service", "service": "ping"},
{"time": "2026-11-07T10:03:20Z", "source": "metrics", "host": "SW-01",
"text": "ssh: rta 1200ms (warn 500, crit 1000)", "severity": "critical",
"state": "critical", "object": "service", "service": "ssh"},
{"time": "2026-11-07T10:04:10Z", "source": "syslog", "host": "SW-01",
"text": "Interface Gi0/1 flapping", "severity": "info",
"state": null, "object": null, "service": null},
{"time": "2026-11-07T10:05:40Z", "source": "traps", "host": "SW-02",
"text": "linkDown on ifIndex 3", "severity": "warning",
"state": null, "object": null, "service": null}
],
"top_events_by_source": {
"monitoring": [
{"time": "2026-11-07T10:02:10Z", "source": "monitoring", "host": "R1",
"text": "Connection timed out", "severity": "critical",
"state": "down", "object": "host", "service": null},
{"time": "2026-11-07T10:02:50Z", "source": "monitoring", "host": "SW-02",
"text": "PING WARNING - rta 620ms", "severity": "warning",
"state": "warning", "object": "service", "service": "ping"}
],
"syslog": [
{"time": "2026-11-07T10:04:10Z", "source": "syslog", "host": "SW-01",
"text": "Interface Gi0/1 flapping", "severity": "info",
"state": null, "object": null, "service": null}
],
"traps": [
{"time": "2026-11-07T10:05:40Z", "source": "traps", "host": "SW-02",
"text": "linkDown on ifIndex 3", "severity": "warning",
"state": null, "object": null, "service": null}
],
"metrics": [
{"time": "2026-11-07T10:03:20Z", "source": "metrics", "host": "SW-01",
"text": "ssh: rta 1200ms (warn 500, crit 1000)", "severity": "critical",
"state": "critical", "object": "service", "service": "ssh"}
],
"otel_logs": [],
"otel_traces": []
},
"reason": ["Common dependency: Core router (R1)", "Events within 4 minutes"],
"reasons": [
{"code": "common_dependency", "params": {"host": "R1"}},
{"code": "time_concentration", "params": {"minutes": 4}}
],
"context": {
"host": "R1", "address": "10.20.0.1", "subnet": "10.20.0.0/24",
"subnet_name": "Madrid core", "hostgroups": ["Madrid"], "location": "Madrid",
"role": "router",
"first_event": {"time": "2026-11-07T10:02:10Z", "source": "monitoring", "host": "R1",
"text": "R1 is down", "severity": "critical", "state": "down",
"object": "host", "service": null},
"host_sequence": [
{"host": "R1", "first_event_at": "2026-11-07T10:02:10Z", "state": "down"},
{"host": "SW-01", "first_event_at": "2026-11-07T10:03:20Z", "state": "unreachable"},
{"host": "SW-02", "first_event_at": "2026-11-07T10:05:40Z", "state": "unreachable"}
],
"host_sequence_truncated": false,
"scope": {"affected_hosts": 3, "total_hosts": 12, "anchor_state": "down"},
"host_states": {"up": 0, "down": 1, "unreachable": 2, "unknown": 0},
"top_services": [{"service": "ssh", "events": 2, "hosts": 1}],
"host_events": 3
},
"dependencies": {
"host": "R1", "state": "down",
"children": [{"host": "SW-01", "state": "unreachable", "children": []},
{"host": "SW-02", "state": "unreachable", "children": []}],
"parents": [{"host": "FW-01", "state": "up"}],
"truncated": false
},
"investigate": {"target": "host", "host_name": "R1",
"host_display_name": "Core router", "last_state_change": 1794045730}
}
]
}
window: the exact range that was analysed, in ISO 8601 UTC. Send itsfromandtoastime_fromandtime_toto request the full sequence.periodis the preset that produced it, ornullwhen the window came fromtime_fromortime_to.summary:events_analyzedis the number of events in the groups (also those of groups cut by the 20-group cap).events_matchedis the raw total of matching events in the sources; it is never belowevents_analyzedand is larger when a source was sampled.related_groupscounts the groups whose relation is notsingle_host.affected_hostsis the number of hosts with at least one event.groupsare ordered with the correlated groups first (most events first) and thesingle_hostgroups after them. When more than 20 groups exist, the cap drops thesingle_hostgroups first andtruncatedistrue.started_atandended_atcome from the problem events only (monitoring,traps,metricsandotel_traces). Syslog andotel_logslines never move them.sampled:monitoringkeeps the newest 10000 alerts andtrapsthe newest 1000 events;metricsreads up to 1000 series, and it is sampled only when a full page of 1000 series came back.otel_traceskeeps the newest 1000 error spans, one event per trace, and is sampled when more matched.syslogandotel_logsnever set it.syslogis read only for hosts that already have a problem, in the range[first problem - 15 min, last problem + 5 min]of each host and with the latest 20 lines per host. A line without a severity isinfo; a line with one keeps the mapping (0 to 3critical, 4warning, othersinfo).relation:common_dependency,same_subnet,same_hostgrouporsingle_host.nameandreasonare already translated;reasonshas the same information as codes, for clients that build their own text. When the anchor of the group is a host (common_dependencyandsingle_host),nameand the matching entries ofreasonuse the same host label: the display name followed by the technical name in parentheses when they differ, else the technical name.severityof an event:critical,warning,unknownorinfo.stateof an event (nullwhen it does not apply):down,unreachableorunknownfor a monitoring host event;warning,criticalorunknownfor a monitoring service event and for a metric.objectishostorservicefor monitoring events and for metrics, andnullfortraps,syslog,otel_logsandotel_traces. A metric series of the host check is a host event:objectishostandserviceisnull(it is not reported as a service).serviceis the service name of a service event, andnullotherwise. Thetextof a monitoring event does not include the service name; thetextof a service metric keeps the format<service>: <metric> <value><unit> (warn <n>, crit <n>), and thetextof a host metric is the same without the<service>:prefix, so it starts with the metric reading.top_events: at most 20 events of the group, ordered by time.top_events_by_sourcehas always the six keysmonitoring,syslog,traps,metrics,otel_logsandotel_traces, each with at most 10 events (an empty array when the source has none), ordered by time. In both lists the events are chosen by severity first (critical,warning,unknown,info) and, within the same severity, the oldest.contextanddependenciesare always objects when the group could be enriched, even if the main host is not known by the realm inventory: thencontexthas the host and null or empty fields, anddependenciesis a tree with only the root, with stateunknown.context,dependenciesandinvestigateare allnulltogether only when the enrichment of that group failed. Thecontextof a main host without events of its own (for example acommon_dependencyanchor) can include its subnet.contextalso describes the whole group, from data the run already holds (no extra request). They are the first observed signal and the reach of the group, not a cause. The keys are always present:first_event: the earliest problem event of the group inside the analysed window, with the fields of any event. A problem that began before the window shows its first event inside it. Log lines (syslog,otel_logs) are used only when the group has nothing else.host_sequence: the hosts ordered by the time of their first problem event, then by name, each as{host, first_event_at, state}, with the current inventorystate(up,down,unreachableorunknown). It has at most 20 entries (the earliest) andhost_sequence_truncatedistruewhen the group has more hosts.host_display_namescovers these hosts andfirst_event.host.scope:affected_hostsishosts_count.total_hostsis the size of the perimeter of the relation: the inventory hosts of the hostgroup (same_hostgroup), the anchor and every host below it (common_dependency), the hosts whose most specific IPAM prefix is the anchor subnet (same_subnet) or1(single_host). It isnullwhen it cannot be known (inventory unavailable, empty or truncated, or no usable IPAM prefixes) and never belowaffected_hosts.anchor_stateis the current state of the anchor host forcommon_dependencyandsingle_host, andnullotherwise.host_states: the current state of all the hosts of the group, with always the keysup,down,unreachableandunknown.top_services: up to 5 services with problem events, as{service, events, hosts}, ordered byeventsand then by name.host_eventscounts the problem events without a service.
dependencies: the root host with itschildren(the tree towards the hosts of the group).parentslists the parents of the root, at most 5, andtruncatedistruewhen the tree was cut to keep it small.message:nullwhen there are groups. With no groups it says that there were no events in the period for the filters (“the selected period” when the window came fromtime_fromortime_to). When the problem sources (monitoring,traps,metricsandotel_traces) are all inunavailable_sources, nothing could be read (syslogandotel_logsare context only and do not count), so the message says instead that the event sources cannot be read right now and to try again later. If only some sources are unavailable, the “no events” message is kept and the client should showunavailable_sourcesas a notice.message_code: a stable code formessage, which the client can use instead of comparing the translated text.nullwhen there are groups;"no_events"when there are no groups and the period had no events for the filters;"sources_unreadable"whenmonitoring,traps,metricsandotel_tracesare all unavailable (the same rule that picks the “cannot be read” message).messageitself is unchanged.generated_at: when the run was computed, in ISO 8601 UTC with a trailingZand second precision.expires_at:generated_atplus the 30 minutes (1800 s) that a run is kept: the time until which the full-sequence endpoint can serve this run. It is present even when storing the run failed; then the events endpoint answers410anyway. Without a persistent cache the run is not stored and the events endpoint recomputes the window.host_display_names: the available display names, keyed by the technical host name. The map can be incomplete when the realm inventory lacks data; the references in the events and in the dependencies keep using the technical name.investigate: the data sent to the RCA when RCA is selected. The kind and the name of the target depend on the relation of the group, as described above: the hostgroup forsame_hostgroup, the anchor host forcommon_dependencyandsingle_host, and the main host forsame_subnet. For host targets,host_display_nameis the display name of that host (empty when it has none) andlast_state_changeis the start of the group in epoch seconds.
Errors:
400:periodis not one of the allowed values,time_fromortime_tois not a valid date or the window is inverted, in the future or longer than 24 hours ({"error": "time_from must be earlier than time_to"},"time_to cannot be in the future"or"The window cannot be longer than 24 hours", translated), orhostgroupis not valid ({"error": "hostgroup is not valid"}: more than 255 characters or control characters).404: the hostgroup does not exist in the realm, or the realm is not a realm or has no Observability.503: the hostgroup cannot be read right now.403: the profile has no grant for the endpoint.
Read the events of a group
GET on observability_event_correlation_events.
Parameter |
Description |
|---|---|
|
Required. The |
|
Required. The |
|
Required. The |
|
The same hostgroup used in the summary (same validation). |
|
Optional. |
|
Optional search text, without spaces at the ends. It looks in the
technical name and the display name of the host, the service and
the text of the event, ignoring case. It can be combined with
|
|
Page size. Default 50, maximum 500. |
|
Events to skip. Default 0. |
Response, with the events oldest first:
{
"total": 5,
"count": 5,
"limit": 50,
"offset": 0,
"results": [
{"time": "2026-11-07T10:02:10Z", "source": "monitoring", "host": "R1",
"text": "Connection timed out", "severity": "critical",
"state": "down", "object": "host", "service": null},
{"time": "2026-11-07T10:02:50Z", "source": "monitoring", "host": "SW-02",
"text": "PING WARNING - rta 620ms", "severity": "warning",
"state": "warning", "object": "service", "service": "ping"},
{"time": "2026-11-07T10:03:20Z", "source": "metrics", "host": "SW-01",
"text": "ssh: rta 1200ms (warn 500, crit 1000)", "severity": "critical",
"state": "critical", "object": "service", "service": "ssh"},
{"time": "2026-11-07T10:04:10Z", "source": "syslog", "host": "SW-01",
"text": "Interface Gi0/1 flapping", "severity": "info",
"state": null, "object": null, "service": null},
{"time": "2026-11-07T10:05:40Z", "source": "traps", "host": "SW-02",
"text": "linkDown on ifIndex 3", "severity": "warning",
"state": null, "object": null, "service": null}
]
}
total is the number of events of the group, whatever the source and
search. count is the number of events that match them, so it equals
total without filters. results is the page of the matching events, and
limit and offset are the values applied. This is the convention of the
paginated tables of the product (count after the filters, total before
them): a group of 306 events with 270 from monitoring answers total 306
and count 270 for source=monitoring, and a page of limit events. An
offset past the end gives an empty page with the same total and
count. The events have the same fields as the ones
of the summary, including state, object and service.
This endpoint only reads the run that the summary stored for 30 minutes, with the
same time_from, time_to and hostgroup. Without a persistent cache (the default
cache keeps nothing), the endpoint recomputes the window of the summary instead
of answering 410.
Errors:
400:groupis missing,time_fromortime_tois missing ({"error": "time_from and time_to are required"}), orsource,time_from,time_to,hostgroup,limitoroffsetare invalid.404: the group is not in that run. When the cache keeps nothing the run is recomputed with the inventory and IPAM data of that moment, so a group of the summary may no longer exist; a hostgroup that does not exist also gives404(see below).410: no stored run matches the realm,hostgroup,time_fromandtime_to: the run expired (30 minutes), the cache is not available, or thehostgroupor window differ from the ones of the summary:{"error": "This analysis has expired. Run it again."}, translated. After an expiration, run the summary again; do not retry the same request. If410persists right after a new summary, the shared cache is not available: rerunning does not help, so contact the platform administrator.403: the profile has no grant for the endpoint.
When the stored run is read, this endpoint does not read the hostgroup: an
unknown or unreadable hostgroup only gives 404 or 503 on the summary.
When the cache keeps nothing and the run is recomputed, the hostgroup is read
again, so this endpoint can answer 404 (the hostgroup does not exist) or
503 (it cannot be read right now) too.