Personalização do 1.6.x Agente de criação de log para suportar a análise personalizada de várias linhas para aplicativos Java com Log4j em ambientes não orquestrados

Este tutorial demonstra como configurar o tratamento de registros de várias linhas do IBM® Cloud Logs Agente de criação de log para um aplicativo Java usando a estrutura de Log4j estrutura de registro. Essa configuração é para ambientes não orquestrados, por exemplo, Linux e Windows, e modifica o arquivo de configuração. Essa configuração garante que os rastreamentos de pilha e os registros de várias linhas sejam agrupados corretamente em IBM Cloud Logs.

Este tutorial requer a versão IBM Cloud Logs Agente de criação de log 1.6.2 ou posterior.

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 não orquestrados.
- Linux Linux
- WindowsWindows

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 foi implantado em um ambiente não orquestrado.
- Linux Linux
- WindowsWindows

Os arquivos de configuração deste tutorial podem ser encontrados onde os arquivos do pacote foram baixados quando você instalou o Agente de criação de log.

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 manual da análise de várias linhas usando um arquivo de configuração

Se você estiver configurando o Agente de criação de log manualmente usando um arquivo de configuração, poderá configurar a análise de várias linhas editando o arquivo de configuração Agente de criação de log apropriado.

É 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.

Definir o analisador de múltiplas linhas

Defina seu analisador personalizado de várias linhas que corresponda ao padrão de saída Log4j. A regex identifica as linhas que começam com o carimbo de data/hora como novas entradas e trata as linhas subsequentes sem carimbos de data/hora como continuações da entrada anterior. Adicione isso ao seu arquivo Agente de criação de log parsers.conf.

Exemplo:

[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"

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 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 carimbo de data/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.

Aplicar o analisador com o filtro de várias linhas

Adicione um filtro ao seu arquivo Agente de criação de log filters.conf para aplicar o analisador personalizado aos registros que correspondem às tags do seu aplicativo.

Por exemplo:

[FILTER]
    Name              multiline
    Match             kube.*
    Multiline.key_content log
    Multiline.parser  multiline-java-example
    Emitter_Name      multiline-java

Reinicie o agente

Após atualizar o mapa de configuração, reinicie o agente.

Linux Para ambientes Linux, execute:

systemctl daemon-reload && systemctl restart fluent-bit

Windows Para ambientes Windows, execute:

sc.exe stop fluent-bit && sc.exe start fluent-bit

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.

Acesse sua instância IBM Cloud Logs.
Usando a visualização Registros , verifique se as entradas de várias linhas estão agrupadas corretamente.

Os dados de registro agrupados são incluídos no campo log.