Antes de Iniciar

Antes de começar a usar este tutorial, revise as informações a seguir para entender os conceitos de Agente de criação de log e multilinha.

• Saiba mais sobre o Agente de criação de log

• Saiba mais sobre o suporte a várias linhas em ambientes orquestrados

Este tutorial também pressupõe que você tenha:

• Uma instância do IBM Cloud Logs provisionada e configurada.

• O Agente de criação de log implantado em um ambiente orquestrado.

  • Kubernetes Service IBM Cloud Kubernetes Service

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

Exemplo de configuração do site Log4j

Vamos supor que o Log4j do seu aplicativo Java para registrar no console (stdout) seja semelhante ao seguinte:

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

Essa configuração gera logs no formato: yyyy-MM-dd HH:mm:ss.SSS [thread] LEVEL logger - message, seguido de uma nova linha. Mensagens de várias linhas, como rastreamentos de pilha, aparecerão nas linhas subsequentes sem um prefixo de registro de data e hora. Por exemplo:

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

Configuração da análise de várias linhas com Helm

Se estiver implantando o Agente de criação de log usando o Helm, você poderá configurar a análise de várias linhas no arquivo Helm values.yaml.

Ativar a análise de várias linhas

Defina enableMultiline como true em seu arquivo values.yaml para ativar o processamento de várias linhas:

enableMultiline: true

Definir o analisador de múltiplas linhas

Adicione um analisador multilinha personalizado na seção additionalMultilineParsers do seu arquivo values.yaml.

É importante que o padrão definido no arquivo log4j.xml esteja alinhado com o regex no analisador multilinear para garantir o agrupamento adequado dos registros.

Exemplo:

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

A regex pressupõe que cada nova linha de registro começa com um registro de data e hora no formato yyyy-MM-dd HH:mm:ss.SSS. A primeira regra captura as linhas iniciais com registros de data e hora e passa para um estado de continuação. A segunda regra corresponde a qualquer linha que não comece com um registro de data e hora.

Essa abordagem é apenas um exemplo para mostrar como garantir que as linhas de registro de várias linhas, como os rastreamentos de pilha e as exceções do Java, sejam agrupadas como uma única entrada de registro antes de serem encaminhadas para IBM Cloud Logs. Há diferentes maneiras de alcançar o mesmo objetivo.

Definir o pré-processador de várias linhas

Configure um pré-processador na seção multilinePreprocessor para aplicar o analisador aos seus logs.

Por exemplo:

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

Aplique as alterações:

Se você tiver instalado uma versão anterior do Agente de criação de log e tiver atualizado a configuração do agente modificando o mapa de configuração diretamente no cluster, faça uma cópia do mapa de configuração do cluster antes de executar o comando helm upgrade. Quando o site Agente de criação de log for atualizado, todas as alterações feitas no mapa de configuração serão substituídas.

Depois de atualizar o arquivo values.yaml, aplique as alterações executando o seguinte em sua implementação. Isso gerará novamente as configurações necessárias.

helm upgrade

Verifique seus registros de várias linhas

Acesse sua instância IBM Cloud Logs e confirme se as entradas de várias linhas (por exemplo, rastreamentos de pilha) estão agrupadas corretamente.

1. Acesse sua instância IBM Cloud Logs.

2. Usando a visualização Registros , verifique se as entradas de várias linhas estão agrupadas corretamente.