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 siempre warning.

  • 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 es critical, de 13 a 16 es warning y el resto es info.

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 son critical, la 4 es warning y el resto son info. Esta correspondencia se aplica solo a syslog; los logs de agentes siguen la escala de OpenTelemetry descrita arriba (17 o más es critical, de 13 a 16 es warning y el resto es info).

  • 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:

  1. 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”.

  2. Misma subred: los hosts comparten red, por ejemplo “Subred 10.20.0.0/24”.

  3. Mismo grupo de hosts: los hosts comparten un grupo de hosts, por ejemplo “Grupo de hosts Madrid”.

  4. 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?

  1. Abra Operación > Observabilidad > Correlación de eventos en un Reino.

  2. 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.

  3. 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.

  4. 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.

  5. 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

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

observability_event_correlation

Run the analysis and read the groups.

observability_event_correlation_events

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 400 for a request without the header X-Requested-With: XMLHttpRequest;

  • the 403 for 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

time_from

Optional. Start of the analysed window: epoch seconds, epoch milliseconds or ISO 8601 (YYYY-MM-DDThh:mmTZD), like the other date pickers. Truncated to whole seconds. Without it, the window starts 30 minutes before time_to.

time_to

Optional. End of the analysed window, same formats. Without it, the window ends now.

period

Optional shortcut, used only when neither time_from nor time_to is sent (they win otherwise). One of 15m, 30m, 1h, 6h, 24h. Default 30m.

hostgroup

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 its from and to as time_from and time_to to request the full sequence. period is the preset that produced it, or null when the window came from time_from or time_to.

  • summary: events_analyzed is the number of events in the groups (also those of groups cut by the 20-group cap). events_matched is the raw total of matching events in the sources; it is never below events_analyzed and is larger when a source was sampled. related_groups counts the groups whose relation is not single_host. affected_hosts is the number of hosts with at least one event.

  • groups are ordered with the correlated groups first (most events first) and the single_host groups after them. When more than 20 groups exist, the cap drops the single_host groups first and truncated is true.

  • started_at and ended_at come from the problem events only (monitoring, traps, metrics and otel_traces). Syslog and otel_logs lines never move them.

  • sampled: monitoring keeps the newest 10000 alerts and traps the newest 1000 events; metrics reads up to 1000 series, and it is sampled only when a full page of 1000 series came back. otel_traces keeps the newest 1000 error spans, one event per trace, and is sampled when more matched. syslog and otel_logs never set it.

  • syslog is 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 is info; a line with one keeps the mapping (0 to 3 critical, 4 warning, others info).

  • relation: common_dependency, same_subnet, same_hostgroup or single_host. name and reason are already translated; reasons has the same information as codes, for clients that build their own text. When the anchor of the group is a host (common_dependency and single_host), name and the matching entries of reason use the same host label: the display name followed by the technical name in parentheses when they differ, else the technical name.

  • severity of an event: critical, warning, unknown or info.

  • state of an event (null when it does not apply): down, unreachable or unknown for a monitoring host event; warning, critical or unknown for a monitoring service event and for a metric. object is host or service for monitoring events and for metrics, and null for traps, syslog, otel_logs and otel_traces. A metric series of the host check is a host event: object is host and service is null (it is not reported as a service). service is the service name of a service event, and null otherwise. The text of a monitoring event does not include the service name; the text of a service metric keeps the format <service>: <metric> <value><unit> (warn <n>, crit <n>), and the text of 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_source has always the six keys monitoring, syslog, traps, metrics, otel_logs and otel_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.

  • context and dependencies are always objects when the group could be enriched, even if the main host is not known by the realm inventory: then context has the host and null or empty fields, and dependencies is a tree with only the root, with state unknown. context, dependencies and investigate are all null together only when the enrichment of that group failed. The context of a main host without events of its own (for example a common_dependency anchor) can include its subnet.

  • context also 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 inventory state (up, down, unreachable or unknown). It has at most 20 entries (the earliest) and host_sequence_truncated is true when the group has more hosts. host_display_names covers these hosts and first_event.host.

    • scope: affected_hosts is hosts_count. total_hosts is 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) or 1 (single_host). It is null when it cannot be known (inventory unavailable, empty or truncated, or no usable IPAM prefixes) and never below affected_hosts. anchor_state is the current state of the anchor host for common_dependency and single_host, and null otherwise.

    • host_states: the current state of all the hosts of the group, with always the keys up, down, unreachable and unknown.

    • top_services: up to 5 services with problem events, as {service, events, hosts}, ordered by events and then by name. host_events counts the problem events without a service.

  • dependencies: the root host with its children (the tree towards the hosts of the group). parents lists the parents of the root, at most 5, and truncated is true when the tree was cut to keep it small.

  • message: null when 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 from time_from or time_to). When the problem sources (monitoring, traps, metrics and otel_traces) are all in unavailable_sources, nothing could be read (syslog and otel_logs are 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 show unavailable_sources as a notice.

  • message_code: a stable code for message, which the client can use instead of comparing the translated text. null when there are groups; "no_events" when there are no groups and the period had no events for the filters; "sources_unreadable" when monitoring, traps, metrics and otel_traces are all unavailable (the same rule that picks the “cannot be read” message). message itself is unchanged.

  • generated_at: when the run was computed, in ISO 8601 UTC with a trailing Z and second precision.

  • expires_at: generated_at plus 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 answers 410 anyway. 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 for same_hostgroup, the anchor host for common_dependency and single_host, and the main host for same_subnet. For host targets, host_display_name is the display name of that host (empty when it has none) and last_state_change is the start of the group in epoch seconds.

Errors:

  • 400: period is not one of the allowed values, time_from or time_to is 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), or hostgroup is 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

group

Required. The id of a group of the summary.

time_from

Required. The from of the window of the summary, exactly as returned (ISO 8601; epoch seconds and milliseconds are also accepted). The former from is no longer read.

time_to

Required. The to of the window of the summary, same formats. The range cannot be inverted, be in the future or be longer than 24 hours; extreme or invalid dates give 400. The former to is no longer read.

hostgroup

The same hostgroup used in the summary (same validation).

source

Optional. monitoring, syslog, traps, metrics, otel_logs or otel_traces.

search

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 source: the event must meet both filters.

limit

Page size. Default 50, maximum 500.

offset

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: group is missing, time_from or time_to is missing ({"error": "time_from and time_to are required"}), or source, time_from, time_to, hostgroup, limit or offset are 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 gives 404 (see below).

  • 410: no stored run matches the realm, hostgroup, time_from and time_to: the run expired (30 minutes), the cache is not available, or the hostgroup or 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. If 410 persists 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.