Soporte de registros multilínea para Agente de registro en entornos orquestados

Los errores y las trazas de pila pueden abarcar varias líneas y cada línea se envía como una entrada de registro independiente. Para admitir la ingesta de registros multilínea por parte de IBM® Cloud Logs desde aplicaciones, como Java o Python, que se ejecutan en entornos orquestados, como Red Hat OpenShift on IBM Cloud o IBM Cloud Kubernetes Service, debe realizar cambios en la configuración de Agente de registro. Los cambios incluyen el análisis sintáctico necesario para agrupar las líneas de registro que se supone que deben estar juntas como un único registro de registro.

Acerca de multiline

En los clústeres OpenShift y Kubernetes, el sistema de registro captura los registros de los flujos de aplicaciones stdout y stderr. A continuación, añade un prefijo a cada línea de registro con metadatos antes de almacenar los registros en archivos, siguiendo el formato de registro de Container Runtime Interface (CRI).

Este prefijo de línea de registro Kubernetes contiene:

Sello de tiempo: En formato ISO 8601.
Nombre del flujo: stdout o stderr.
Etiqueta: F o P.

El formato de registro CRI utiliza etiquetas para definir si una línea de registro es una única línea de registro o una entrada de registro multilínea. Los valores válidos para la etiqueta son:

Parcial (P): Esta etiqueta se incluye en las líneas de registro que son el resultado de la división de una sola línea de registro en varias líneas por el tiempo de ejecución y la entrada de registro aún no ha terminado.
Completo (F): Esta etiqueta se utiliza para indicar que la entrada de registro está completa. Se utiliza para una entrada de una sola línea de registro o para indicar que es la última línea de la entrada de varias líneas.

2024-03-15T10:30:45.123456789Z stdout F This is a complete log line
2024-03-15T10:30:45.123456789Z stderr P This is the first part of a
2024-03-15T10:30:45.123456789Z stderr F multiline error message

Por defecto, Agente de registro incluye la configuración de Tail plugin con el analizador multilínea cri para soportar la concatenación de estos registros con formato CRI de stdout y stderr en una única línea de registro.

En los entornos Kubernetes que utilizan registros basados en CRI, se recomienda utilizar la configuración Multiline.Parser (establecida por defecto en cri ) para analizar y reensamblar correctamente los registros multilínea generados por los contenedores.

También puede tener aplicaciones, como Java o Python, donde los errores y las trazas de pila pueden abarcar varias líneas, y cada línea se envía como una entrada de registro independiente. Estas aplicaciones pueden generar varias líneas de registro que pueden asociarse entre sí en una única línea de registro. Para gestionar estos registros multilínea a través de Agente de registro, debe configurar un Multiline parser adicional.

Configuración multilínea por defecto

La configuración multilínea por defecto para los registros de IRC se configura y habilita al desplegar Agente de registro.

En Fluent Bit, puede configurar Multiline parser utilizando el analizador multilínea incorporado o un analizador multilínea personalizado.

Por defecto, el Tail plugin que se configura con el Agente de registro se configura con el parser multilínea cri incorporado. Este analizador procesa los registros generados por el motor de contenedores CRI-O y admite la concatenación de entradas de registro.

Por ejemplo, Agente de registro tiene esta configuración por defecto para el soporte multilínea:

    [INPUT]
        Name              tail
        Tag               kube.*
        .....
        Buffer_Chunk_Size 32KB
        Buffer_Max_Size   256KB
        Multiline.parser  cri
        Skip_Long_Lines   On
        Refresh_Interval  10
        storage.type      filesystem
        storage.pause_on_chunks_overlimit on

Configuración de soporte multilínea adicional para aplicaciones

Si tiene aplicaciones, como Java o Python, en las que los errores y las trazas de pila pueden abarcar varias líneas, y cada línea se envía como una entrada de registro independiente, debe configurar el analizador sintáctico multilínea en Agente de registro.

Elija una de las siguientes opciones para configurar Agente de registro con el analizador multilínea:

Despliegue el Agente de registro añadiendo un nuevo valor enableMultiline en el archivo logs-values.yaml que utiliza para desplegar el agente mediante un gráfico Helm. Para obtener más información, consulte Configurar el archivo de valores del gráfico Helm para Agente de registro o Configurar el archivo de valores del gráfico de Helm para Agente de registro.
Actualice Agente de registro a la versión 1.4.1 o superior. Debe actualizar el archivo Helm chart logs-values.yaml con la versión del agente y configurar enableMultiline a true para habilitar el soporte multilínea. Para obtener más información, consulte Actualizar el archivo de valores del gráfico Helm para el agente de registro.

Añadir un analizador multilínea personalizado

Para crear un analizador multilínea personalizado para usar con Agente de registro, siga las instrucciones en Analizadores multilínea configurables. Definirá una expresión regular personalizada para determinar el patrón multilínea.

La configuración de Agente de registro también debe incluir un FILTER después del complemento INPUT. El filtro aplicará el patrón del MULTILINE_PARSER configurado. El valor Name de MULTILINE_PARSER debe coincidir con el valor Multiline.parser de FILTER.

filter-multiline.conf: |
    [FILTER]
        Name              multiline
        Match             *
        Multiline.parser  INSERT_CUSTOM_PARSER_NAME
        Multiline.key_content log

Añadir soporte multilínea a las aplicaciones

Si tiene el Agente de registro desplegado y tiene aplicaciones como Java o Python, donde los errores y las trazas de pila pueden abarcar varias líneas, y cada línea se envía como una entrada de registro independiente, puede actualizar la configuración de su agente y configurar el analizador multilínea.

Complete los siguientes pasos para añadir soporte multilínea en Agente de registro:

Inicie una sesión en el clúster. Para más información, consulte Acceda a su clúster.

En el mapa de configuración de Agente de registro (inputs.conf), añada el analizador multilínea.

La configuración de Agente de registro debe tener el @INCLUDE para el filtro multilínea justo después del plug-in de entrada.

fluent-bit.conf: |
[SERVICE]
  Flush                   1
  Log_Level               info
  Daemon                  off
  Parsers_File            parsers.conf
  Plugins_File            plugins.conf

  ...


@INCLUDE input-kubernetes.conf
@INCLUDE filter-multiline.conf

...

input-kubernetes.conf: |
[INPUT]
    Name              tail
    Tag               kube.*
    .....
    Buffer_Chunk_Size 32KB
    Buffer_Max_Size   256KB
    Multiline.parser  cri
    Skip_Long_Lines   On
    Refresh_Interval  10
    storage.type      filesystem
    storage.pause_on_chunks_overlimit on

filter-multiline.conf: |
[FILTER]
    Name              multiline
    Match             *
    Multiline.parser  multiline-java-example
    Multiline.key_content log

parsers.conf: |
...
[MULTILINE_PARSER]
    Name            multiline-java-example
    Type            regex
    Flush_timeout   500
    Rule            "start_state"     "/^(\d+-\d+-\d+ \d+:\d+:\d+\.\d+)(.*)$/"     "cont"
    Rule            "cont"            "/^(?!\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}).*$/"     "cont"
...

Reinicie los pods de agentes.

Para clusters Kubernetes, ejecute:

kubectl -n ibm-observe rollout restart ds/logs-agent

Para clusters OpenShift, ejecute:

oc -n ibm-observe rollout restart ds/logs-agent

Configuración de la compatibilidad multilínea para clústeres con varios tiempos de ejecución y requisitos de análisis sintáctico

Si tiene clústeres que ejecutan aplicaciones con varios lenguajes o tiempos de ejecución diferentes (por ejemplo, Java, Go y Python ), es posible que necesite gestionar registros multilínea de varias fuentes. Si ya dispone de un analizador multilínea personalizado para Java, puede combinarlo con analizadores integrados para otros tiempos de ejecución como Go y Python. Esto garantiza que todos los registros se analicen correctamente y se envíen como entradas agrupadas correctamente a IBM® Cloud Logs.

Al especificar varios analizadores sintácticos (integrados y personalizados) en una lista separada por comas, Agente de registro probará cada uno de ellos en secuencia hasta encontrar una coincidencia.

Configuración de múltiples analizadores sintácticos mediante Helm

Si utiliza Helm para configurar su entorno orquestado, actualice la sección multilinePreprocessor para hacer referencia tanto a los analizadores integrados (por ejemplo, go, python) como a sus analizadores personalizados en una lista separada por comas.

Por ejemplo:

multilinePreprocessor:
  - name: multiline
    multiline.parser: go, python, nodejs, ruby, multiline-java-example, multiline-nodejs-winston
    multiline.key_content: log

Si ha instalado una versión anterior de Agente de registro y ha actualizado la configuración del agente modificando el mapa de configuración directamente en el clúster, haga una copia de su mapa de configuración desde el clúster antes de ejecutar el comando helm upgrade. Cuando se actualice Agente de registro, se sobrescribirá cualquier cambio realizado en el mapa de configuración.

Tras actualizar el archivo values.yaml, ejecute helm upgrade para aplicar los cambios. Verifique su configuración comprobando los registros de diferentes tiempos de ejecución en IBM Cloud Logs para asegurarse de que la agrupación multilínea funciona en todas las configuraciones.

Más información y ejemplos

Para obtener más información y tutoriales con escenarios de ejemplo para configurar el procesamiento multilínea, consulte los siguientes temas.

Recursos adicionales para el tratamiento multilínea Agente de registro
Para obtener información sobre	Véase
Configuración del soporte multilínea para Agente de registro en Linux	Tema
Configuración del soporte multilínea para Agente de registro en Windows	Tema
Análisis sintáctico multilínea para aplicaciones Java con Log4j	Guía de aprendizaje
Análisis sintáctico multilínea mediante Helm para aplicaciones Java con Log4j	Guía de aprendizaje
Análisis sintáctico multilínea para aplicaciones Node.js con Winston	Guía de aprendizaje
Análisis sintáctico multilínea mediante Helm para aplicaciones Node.js con Winston	Guía de aprendizaje