.. _event_correlation: 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: #. **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 ----------------------- * :ref:`action_rca`: análisis de causa raíz utilizado por la acción **RCA**. * :ref:`rca_realm_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 ====================================================== ============================================ ``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 ```` and ````, 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": ""}``, 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 ``: (warn , crit )``, and the ``text`` of a host metric is the same without the ``:`` 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.