Resumen
Zylon admite almacenamiento interno de logs y entrega externa por syslog y HTTP.- La entrega por syslog esta pensada para SIEMs y colectores que aceptan eventos syslog o CEF.
- La entrega por HTTP esta pensada para endpoints de ingesta estructurada, destinos cloud y pipelines gestionados por el cliente.
- La entrega es asincrona.
- Con
failurePolicy: "drop", la entrega evita bloquear el camino critico cuando las colas estan llenas. - Los eventos entregados se pueden filtrar por patrones de accion e IDs de organizacion.
- Los logs almacenados permanecen en el despliegue Zylon del cliente salvo que se habilite entrega externa de logs por syslog o HTTP.
/etc/zylon/zylon-conf.yaml y ejecuta sudo zylon-cli sync para aplicar los cambios. Para instalaciones gestionadas directamente con Helm, usa las mismas claves en el YAML de valores de Helm de Zylon. El chart mapea estos valores a la configuración interna del backend.
Para gobernanza, auditabilidad, soporte de trazabilidad para EU AI Act, preservacion de evidencia y retencion, consulte Auditabilidad y gobernanza de IA: Logging, evidencia y entrega a SIEM.
Enviar logs a tu SIEM
Para un SIEM propio con un endpoint HTTPS de ingesta JSON, empieza con la entrega HTTP de esta sección. Si tu colector acepta syslog o CEF, usa la configuración de syslog. El almacenamiento interno (logging.storage.enabled) está habilitado por defecto. La entrega externa por syslog y HTTP está deshabilitada por defecto. Habilitar solo el almacenamiento no envía eventos a tu SIEM. La entrega reenvía eventos nuevos; no reproduce automáticamente el historial almacenado. Usa la API de logging de Backoffice para recuperar registros históricos.
1. Preparar el colector
Crea un endpoint HTTPS accesible desde el backend de Zylon que acepte solicitudesPOST con registros de log JSON. Devuelve una respuesta HTTP 2xx después de aceptar la solicitud. Si requiere autenticación bearer, prepara su token de ingesta.
El payload HTTP usa el marcador de esquema zylon.canonical_json.v1. Una solicitud con un evento contiene un objeto JSON; los lotes con varios eventos contienen un array JSON. El ejemplo usa maxEvents: 1 para validar un registro cada vez. Para usar después el tamaño predeterminado de 25, confirma que tu colector también acepta arrays.
El sobre HTTP contiene schema, severity, outcome, actor y log. Mapea log.event, log.action, log.id y log.start_timestamp a los campos de tu SIEM. Estos campos están anidados bajo log, no en el nivel superior. Deduplica los reintentos usando log.id.
Metadatos de entrega e identificadores de actor
Metadatos de entrega e identificadores de actor
La selección de actor usa la primera fila que coincide:
Para actores de token/usuario,
actor_display es log.account_email si no está vacío ni contiene solo espacios; en caso contrario, el ID de actor seleccionado. Los actores de sistema/desconocidos también usan su valor literal como etiqueta. Un ID de miembro o correo por sí solo no selecciona user; la identidad de token/cuenta tiene prioridad sobre system_event.Usa log.account_id para correlacionar cuentas y log.ws_member_id para correlacionar miembros del espacio de trabajo, cuando estén disponibles. Un ID de actor user puede identificar cualquiera de esos dos tipos de registro; no lo trates siempre como un ID de cuenta. actor_display es una etiqueta, no una clave estable para relacionar registros.Si una acción no tiene un mapeo específico de severidad, los eventos correctos de Backoffice usan medium y los demás eventos correctos usan low; los fallos de Backoffice usan high y los demás fallos usan medium. Un actor unknown no implica un resultado desconocido ni cambia la severidad.Ejemplo de evento HTTP (campos seleccionados)
Ejemplo de evento HTTP (campos seleccionados)
action. Con lotes habilitados, acepta tanto un objeto como un array, según el número de eventos listos para enviar.
La captura de mensajes de solicitud y respuestas del chat del gateway (
features.audit.enabled) está habilitada por defecto. Los registros reenviados pueden contener ese contenido de chat capturado. Revisa Registro de Auditoría antes de habilitar la entrega. El parámetro include de la API no filtra los registros reenviados.2. Configurar Zylon
Combina este ejemplo con/etc/zylon/zylon-conf.yaml, conservando los ajustes existentes. Sustituye la URL y el token por los de tu colector; el token pertenece a tu SIEM, no a la API de Backoffice de Zylon. Si el colector no requiere autenticación bearer, omite el bloque auth.
3. Aplicar la configuración
4. Verificar un evento nuevo
Tras aplicar la configuración, crea un proyecto de prueba en el Workspace. Inspecciona la solicitud recibida por tu colector y confirma el marcadorzylon.canonical_json.v1 y log.action: "ws.project.create". Confirma después que el registro aparece en la búsqueda o vista de eventos de tu SIEM.
Si no llega, revisa las advertencias de entrega del backend, la conectividad, las respuestas del colector, la autenticación y los filtros. Las respuestas HTTP 4xx no se reintentan; corrige la URL, autenticación, cabeceras o parser antes de repetir la prueba. Consulta Resolución de problemas para otros síntomas.
La política predeterminada
failurePolicy: "drop" puede descartar eventos cuando la cola está llena. La entrega externa no tiene spool persistente en disco. Conserva el almacenamiento interno para investigar y verifica por separado la retención del colector.5. Elegir la retención interna y del SIEM
La limpieza de logs almacenados está deshabilitada por defecto: los logs no se borran automáticamente tras180 días. Para activar el borrado programado, usa Limpieza solo de logs. Configura por separado la retención de las copias de tu SIEM.
Vista rapida
Syslog y HTTP pueden habilitarse al mismo tiempo. Cuando ambos estan habilitados, Zylon envia los logs coincidentes a ambos destinos.
Antes de configurar la entrega
- Confirme que el endpoint del colector es accesible desde el backend de Zylon.
- Confirme host o URL y puerto.
- Seleccione transporte y formato.
- Decida el comportamiento de verificacion de certificados TLS.
- Configure el input, indice, parser o ruta de ingesta en el colector.
- Revise los requisitos de retencion en Zylon y en los sistemas externos.
- Revise filtros para no excluir eventos de auditoria requeridos.
Almacenamiento y retencion
El almacenamiento interno se controla bajologging.storage.
Claves de almacenamiento
Claves de retencion
La limpieza de logs internos se controla bajozylonBackend.scheduler.cleanup.
Configuracion del programador:
Bajo
logging:
La limpieza de logs almacenados esta deshabilitada por defecto. El valor
180 dias aplica solo despues de habilitar tanto el programador de limpieza como la limpieza de logs almacenados.Configurar limpieza solo de logs
Combina este ejemplo con tu configuración solo cuando quieras activar el borrado interno de logs. Programa revisiones diarias a las03:00 UTC con una ventana de retención de 180 días:
cleanup.enabled como cleanup.logging.enabled deben ser true. workspace.enabled: false mantiene deshabilitado el borrado permanente de Workspace en este ejemplo; el valor predeterminado en Helm es true, por lo que debes revisar este flag antes de habilitar el programador compartido. Conserva tu política de limpieza de Workspace si ya la utilizas.
Tras aplicar la configuración con sudo zylon-cli sync, cada ejecución programada borra definitivamente registros persistidos hace más de 180 días, junto con sus detalles de log asociados. La antigüedad usa el timestamp created_at del registro almacenado, asignado al persistir logs nuevos. Los registros históricos migrados desde versiones anteriores pueden usar la hora de inicio del evento. Los registros elegibles permanecen hasta una ejecución de limpieza correcta. La limpieza afecta a todas las organizaciones y familias de logs; los filtros de entrega externa no limitan el borrado.
Para detener la limpieza de logs, configura zylonBackend.scheduler.cleanup.logging.enabled: false. Deshabilitar logging.storage.enabled detiene la persistencia de logs nuevos; no borra registros existentes. La limpieza no borra copias enviadas a tu SIEM ni cambia su política de retención.
Entrega por syslog
La entrega por syslog envia registros formateados a un colector por TCP, TLS o UDP. Userfc5424_json para pipelines syslog estructurados. Use cef cuando el colector tenga un input CEF nativo.
Claves de syslog
Bajologging.delivery.syslog:
Claves opcionales de syslog
Claves opcionales de syslog
Los filtros y ajustes opcionales de entrega, cola, lotes y TLS se configuran bajo sus bloques anidados correspondientes en
logging.delivery.syslog.Bajo filters:Bajo
delivery:Bajo
delivery.reconnect:Bajo
delivery.queue:Bajo
delivery.batch:Bajo
tls:Ejemplo completo de syslog
Entrega por HTTP
La entrega por HTTP envia registros JSON estructurados a un colector HTTP. El formato admitido escanonical_json; el esquema es zylon.canonical_json.v1.
HTTP admite POST, autenticacion bearer opcional, cabeceras estaticas con Header=Value o Header: Value, reintentos para errores de red y respuestas 5xx, y no reintenta respuestas 4xx.
Claves de HTTP
Bajologging.delivery.http:
Claves opcionales de HTTP
Claves opcionales de HTTP
La autenticacion y los ajustes opcionales de filtros, entrega, cola y lotes se configuran bajo sus bloques anidados correspondientes en
logging.delivery.http.Bajo auth:Bajo
filters:Bajo
delivery:Bajo
delivery.retry:Bajo
delivery.queue:Bajo
delivery.batch:Ejemplo completo de HTTP
Filtrado de eventos entregados
Syslog y HTTP usan el mismo comportamiento bajofilters.
Orden de evaluacion:
- Patrones de exclusion de accion.
- Patrones de inclusion de accion.
- IDs de organizacion incluidos.
Controles operativos
Mantenga todos los nodos backend de Zylon sincronizados con una fuente horaria confiable como NTP. El chart Helm configuraUTC por defecto para el programador de limpieza; si el ajuste runtime se omite fuera de Helm, el backend usa la zona horaria JVM del servidor. Los registros deben revisarse en UTC para correlacion forense entre sistemas.
Trate cambios en logging.storage, logging.delivery, filtros, retencion y destinos de colector como cambios de despliegue auditables. Capture aprobaciones y diffs en GitOps, change management, auditoria Kubernetes o el sistema de auditoria de infraestructura usado por el cliente.
Los esquemas entregados usan marcadores como zylon.rfc5424_json.v1 y zylon.canonical_json.v1. Los parsers SIEM deben enrutar por marcador y validar compatibilidad al actualizar.
Politicas de fallo
El spooling de entrega externa respaldado por disco no esta implementado.
Estas políticas solo controlan la presión de la cola.
block no garantiza la entrega: una respuesta no reintentable o el agotamiento de reintentos puede descartar el lote. Las respuestas HTTP 4xx, incluido 429, no se reintentan; los errores de red y HTTP 5xx sí se reintentan según la configuración. No hay spool persistente ni recuperación automática desde el almacenamiento interno.
Validacion local
- Habilite un canal de entrega.
- Aplique la configuracion.
- Ejecute una accion de API que emita un log, como crear un proyecto o un token de API.
- Consulte el colector.
- Confirme que aparecen
event,action,log.idy campos de actor esperados. - Revise logs del backend si la entrega no llega.
zylon.rfc5424_json.v1para syslog RFC 5424 JSON.CEF:0|Zylonpara CEF.zylon.canonical_json.v1para HTTP.- Una accion conocida como
ws.project.create.