Antes de empezar

Antes de empezar a utilizar este tutorial, revise la siguiente información para comprender los conceptos de Agente de registro y multilínea.

• Infórmese sobre la Agente de registro

• Más información sobre la compatibilidad multilínea en entornos orquestados

Este tutorial también asume que usted tiene:

• Una instancia de IBM Cloud Logs aprovisionada y configurada.

• El Agente de registro desplegado en un entorno orquestado.

  • Kubernetes Service IBM Cloud Kubernetes Service

  • Red Hat OpenShift on IBM Cloud Red Hat OpenShift on IBM Cloud

Ejemplo de configuración de Log4j

Supongamos que el Log4j de su aplicación Java para registrar en la consola (stdout) es similar al siguiente:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n" />
        </Console>
    </Appenders>
    <Loggers>
        <Root level="info">
            <AppenderRef ref="Console"/>
        </Root>
    </Loggers>
</Configuration>

Esta configuración muestra los registros en el formato: yyyy-MM-dd HH:mm:ss.SSS [thread] LEVEL logger - message seguido de una nueva línea. Los mensajes multilínea, como las trazas de pila, aparecerán en líneas posteriores sin prefijo de fecha y hora. Por ejemplo:

2025-07-28 10:32:15.423 [main] INFO com.example.logging.Main - Application starting up
2025-07-28 10:32:16.191 [main] INFO com.example.logging.Main - This is an info message
2025-07-18 10:32:18.801 [main] ERROR com.example.logging.Main - This is an error message
java.lang.NullPointerException: null
at com.example.logging.Main.lambda$main$3(Main.java:30) ~[java-log4j-1.0.0.jar:?]
at spark.RouteImpl$1.handle(RouteImpl.java:72) ~[java-log4j-1.0.0.jar:?]
at spark.http.matching.Routes.execute(Routes.java:61) ~[java-log4j-1.0.0.jar:?]
at spark.http.matching.MatcherFilter.doFilter(MatcherFilter.java:134) ~[java-log4j-1.0.0.jar:?]
at spark.embeddedserver.jetty.JettyHandler.doHandle(JettyHandler.java:50) ~[java-log4j-1.0.0.jar:?]
at org.eclipse.jetty.server.session.SessionHandler.doScope(SessionHandler.java:1584) ~[java-log4j-1.0.0.jar:?]
at org.eclipse.jetty.server.handler.ScopedHandler.handle(ScopedHandler.java:141) ~[java-log4j-1.0.0.jar:?]
at org.eclipse.jetty.server.handler.HandlerWrapper.handle(HandlerWrapper.java:127) ~[java-log4j-1.0.0.jar:?]
at org.eclipse.jetty.server.Server.handle(Server.java:501) ~[java-log4j-1.0.0.jar:?]
at org.eclipse.jetty.server.HttpChannel.lambda$handle$1(HttpChannel.java:383) ~[java-log4j-1.0.0.jar:?]
at org.eclipse.jetty.server.HttpChannel.dispatch(HttpChannel.java:556) [java-log4j-1.0.0.jar:?]
at org.eclipse.jetty.server.HttpChannel.handle(HttpChannel.java:375) [java-log4j-1.0.0.jar:?]
at org.eclipse.jetty.server.HttpConnection.onFillable(HttpConnection.java:273) [java-log4j-1.0.0.jar:?]
at org.eclipse.jetty.io.AbstractConnection$ReadCallback.succeeded(AbstractConnection.java:311) [java-log4j-1.0.0.jar:?]
at org.eclipse.jetty.io.FillInterest.fillable(FillInterest.java:105) [java-log4j-1.0.0.jar:?]
at org.eclipse.jetty.io.ChannelEndPoint$1.run(ChannelEndPoint.java:104) [java-log4j-1.0.0.jar:?]
at org.eclipse.jetty.util.thread.QueuedThreadPool.runJob(QueuedThreadPool.java:806) [java-log4j-1.0.0.jar:?]
at org.eclipse.jetty.util.thread.QueuedThreadPool$Runner.run(QueuedThreadPool.java:938) [java-log4j-1.0.0.jar:?]
at java.lang.Thread.run(Unknown Source) [?:?]

Configuración del análisis sintáctico multilínea con Helm

Si despliega Agente de registro utilizando Helm, puede configurar el análisis sintáctico multilínea en el archivo Helm values.yaml.

Activar el análisis sintáctico multilínea

Establezca enableMultiline en true en su archivo values.yaml para activar el procesamiento multilínea:

enableMultiline: true

Definir el analizador sintáctico multilínea

Añada un analizador multilínea personalizado en la sección additionalMultilineParsers de su archivo values.yaml.

Es importante que el patrón definido en el archivo log4j.xml coincida con el regex del analizador multilínea para garantizar una agrupación correcta de los registros.

Ejemplo:

additionalMultilineParsers:
  - name: multiline-java-example
    type: regex
    flush_timeout: 500
    rules:
      - state: start_state
        regex: '/^(\d+-\d+-\d+ \d+:\d+:\d+\.\d+)(.*)$/'
        next_state: cont
      - state: cont
        regex: '/^(?!\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}).*$/'
        next_state: cont

La regex asume que cada nueva línea de registro comienza con una marca de tiempo en el formato yyyy-MM-dd HH:mm:ss.SSS. La primera regla captura las líneas de inicio con marcas de tiempo y pasa a un estado de continuación. La segunda regla coincide con cualquier línea que no empiece por una marca de tiempo.

Este enfoque es sólo un ejemplo para mostrarle cómo asegurarse de que las líneas de registro multilínea, como Java stack traces y excepciones, se agrupan como una única entrada de registro antes de reenviarlas a IBM Cloud Logs. Hay diferentes maneras de conseguir lo mismo.

Definir el preprocesador multilínea

Configure un preprocesador en la sección multilinePreprocessor para aplicar el analizador sintáctico a sus registros.

Por ejemplo:

multilinePreprocessor:
  - name: multiline
    multiline.parser: multiline-java-example
    multiline.key_content: log

Aplique los cambios.

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, aplique los cambios ejecutando lo siguiente en su implantación. Esto regenerará las configuraciones necesarias.

helm upgrade

Verifique sus registros multilínea

Acceda a su instancia IBM Cloud Logs y confirme que sus entradas multilínea (por ejemplo, stack traces) están agrupadas correctamente.

1. Acceda a su instancia IBM Cloud Logs.

2. Uso del icono de registros y verifique que sus entradas de varias líneas estén agrupadas correctamente.