Prima di iniziare

Prima di iniziare a utilizzare questa esercitazione, si consiglia di leggere le seguenti informazioni per comprendere i concetti di Agent di registrazione e multilinea.

• Imparare a conoscere il Agent di registrazione

• Informazioni sul supporto multilinea negli ambienti orchestrati

Questa esercitazione presuppone anche che siate in possesso di:

• Un'istanza di IBM Cloud Logs è stata fornita e configurata.

• Il sito Agent di registrazione è distribuito in un ambiente orchestrato.

  • Kubernetes Service IBM Cloud Kubernetes Service

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

Esempio di configurazione di Log4j

Supponiamo che l'applicazione Java Log4j da registrare nella console (stdout) sia simile alla seguente:

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

Questa configurazione produce i log nel formato: yyyy-MM-dd HH:mm:ss.SSS [thread] LEVEL logger - message, seguito da una newline. I messaggi su più righe, come le tracce di stack, appariranno su righe successive senza il prefisso del timestamp. Ad esempio:

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) [?:?]

Configurazione dell'analisi multilinea con Helm

Se si distribuisce Agent di registrazione usando Helm, si può configurare l'analisi multilinea nel file Helm values.yaml.

Abilita l'analisi multilinea

Impostare enableMultiline su true nel file values.yaml per attivare l'elaborazione multilinea:

enableMultiline: true

Definire il parser multilinea

Aggiungere un parser multilinea personalizzato nella sezione additionalMultilineParsers del file values.yaml.

È importante che lo schema definito nel file log4j.xml sia in linea con la regex del parser multilinea per garantire un corretto raggruppamento dei registri.

Esempio:

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 presuppone che ogni nuova riga di log inizi con un timestamp nel formato yyyy-MM-dd HH:mm:ss.SSS. La prima regola cattura le righe iniziali con i timestamp e passa a uno stato di continuazione. La seconda regola corrisponde a qualsiasi riga che non inizia con un timestamp.

Questo approccio è solo un esempio per mostrare come garantire che le righe di log multiline, come le tracce dello stack di Java e le eccezioni, siano raggruppate come una singola voce di log prima di inoltrarle a IBM Cloud Logs. Ci sono diversi modi per ottenere la stessa cosa.

Definire il preprocessore multilinea

Configurare un preprocessore nella sezione multilinePreprocessor per applicare il parser ai log.

Ad esempio:

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

Applicare le modifiche.

Se è stata installata una versione precedente di Agent di registrazione e si è aggiornata la configurazione dell'agente modificando la mappa di configurazione direttamente nel cluster, eseguire una copia della mappa di configurazione dal cluster prima di eseguire il comando helm upgrade. Quando il sito Agent di registrazione viene aggiornato, le modifiche apportate alla mappa di configurazione vengono sovrascritte.

Dopo aver aggiornato il file values.yaml, applicare le modifiche eseguendo il seguente comando sull'installazione client. In questo modo si rigenerano le configurazioni necessarie.

helm upgrade

Verificare i log multilinea

Accedere all'istanza di IBM Cloud Logs e verificare che le voci multilinea (ad esempio, le tracce di stack) siano raggruppate correttamente.

1. Accedere all'istanza IBM Cloud Logs.

2. Utilizzando la vista Registri , verificare che le voci multilinea siano raggruppate correttamente.