開始之前

在開始使用本教學之前，請檢閱下列資訊，以瞭解 記載代理程式 和多行概念。

• 瞭解 記載代理程式

• 瞭解協調環境中的多線支援

本教學也假設您有：

• 已配置的 IBM Cloud Logs 實例。

• 記載代理程式 部署在協調環境中。

  • Kubernetes Service IBM Cloud Kubernetes Service

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

Log4j 設定範例

讓我們假設您的 Java 應用程式的 Log4j 要記錄到控制台 (stdout) 與下列內容相似：

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

此設定會以格式輸出記錄：yyyy-MM-dd HH:mm:ss.SSS [thread] LEVEL logger - message，之後是換行。 多行訊息（例如堆疊追蹤）會顯示在沒有時間戳記前綴的後續行中。 例如：

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

設定多行解析與 Helm

如果您使用 Helm 部署 記載代理程式，您可以在 Helm values.yaml 檔案中設定多行解析。

啟用多行解析

在 values.yaml 檔案中設定 enableMultiline 為 true，以啟動多行處理：

enableMultiline: true

定義多行解析器

在 values.yaml 檔案的 additionalMultilineParsers 區段下新增自訂多行解析器。

log4j.xml 檔案中定義的模式必須與多行解析器中的 regex 一致，以確保正確的日誌群組。

範例：

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

此 regex 假定每一行新日誌都以格式為 yyyy-MM-dd HH:mm:ss.SSS 的時間戳開始。 第一條規則擷取具有時間戳記的起始行，並移動到延續狀態。 第二條規則會匹配任何不是以時間戳開始的行。

這個方法只是一個範例，讓您知道如何確保多行記錄線（例如 Java 堆疊追蹤和異常）在轉送至 IBM Cloud Logs 之前，先歸類為單一記錄項目。 要達到相同的目的，有不同的方法。

定義多行預處理器

在 multilinePreprocessor 區段下設定預處理器，將解析器套用至您的日誌。

例如：

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

套用變更。

如果您已安裝先前版本的 記載代理程式，並透過直接在群集中修改配置映射更新了代理程式組態，請在執行 helm upgrade 指令之前，先從群集中複製一份配置映射。 更新 記載代理程式 時，對設定映射所做的任何變更都會被覆蓋。

更新 values.yaml 檔案後，在您的部署上執行下列步驟，套用變更。 這將會重新產生必要的設定。

helm upgrade

驗證您的多行日誌

存取您的 IBM Cloud Logs 範例，並確認您的多行項目（例如堆疊追蹤）已正確分組。

1. 存取您的 IBM Cloud Logs 實例。

2. 使用日誌 檢視，驗證您的多行項目是否已正確分組。