全部產品
Search

搜尋本產品

    Simple Log Service：使用Logtail SPL解析日誌

    文件中心

    Simple Log Service：使用Logtail SPL解析日誌

    更新時間：May 30, 2026

    iLogtail 支援三種處理模式：原生外掛程式模式（C++實現，效能最強）、拓展外掛程式模式（Go實現，生態豐富且靈活）和SPL模式（在iLogtail 2.0中引入，結合了效能和靈活性）。通過編寫SPL語句，您可以充分利用其計算能力來處理資料。本文將介紹如何使用SPL語句實現與其他兩種處理模式相同的功能。

    前提條件

    使用限制

    • SPL採集日誌僅支援Logtail 2.0及以上版本。

    • 文本日誌採集支援通過控制台配置，其他資料接入暫不支援控制台配置，請通過API或CRD配置。

    使用樣本

    SPL 使用樣本請參見使用SPL採集文本日誌。

    SPL 使用情境請參見SPL 處理資料最佳實務。

    操作步驟

    在修改Logtail配置時添加SPL

    1. 登入Log Service控制台。

    2. 在Project列表地區，單擊目標Project。

    3. 在日誌存儲 > 日誌庫頁簽中，單擊目標日誌庫前面的>，依次選擇數據接入 > Logtail設定。

    4. 在Logtail設定列表中，單擊目標Logtail配置後操作列的管理Logtail配置。

    5. 單擊頁面上方的編輯，在頁面下方的處理配置地區，處理配置中處理模式選擇SPL，然後單擊保存。

      全域配置

      配置項

      說明

      配置名稱

      Logtail配置名稱，在其所屬Project內必須唯一。建立Logtail配置成功後，無法修改其名稱。

      日誌主題類型

      選擇日誌主題（Topic）的產生方式。更多資訊，請參見日誌主題。

      • 機器組Topic：設定為機器組的Topic屬性，用於明確區分不同機器組產生的日誌。

      • 檔案路徑提取：設定為檔案路徑正則，則需要設定自訂正則，用Regex從路徑裡提取一部分內容作為Topic。用於區分不同源產生的日誌。

      • 自訂：自訂日誌主題。

      進階參數

      其它可選的與配置全域相關的進階功能參數，請參見建立Logtail流水線配置。

      輸入配置

      配置項

      說明

      檔案路徑

      根據日誌在主機（例如ECS）上的位置，設定日誌目錄和檔案名稱。

      • 如果目標主機是Linux系統，則日誌路徑必須以正斜線（/）開頭，例如/apsara/nuwa/**/app.Log。

      • 如果目標主機是Windows系統，則日誌路徑必須以盤符開頭，例如C:\Program Files\Intel\**\*.Log。

      目錄名和檔案名稱均支援完整模式和萬用字元模式，檔案名稱規則請參見Wildcard matching。其中，日誌路徑萬用字元只支援星號（*）和半形問號（?）。

      記錄檔尋找模式為多層目錄匹配，即合格指定目錄（包含所有層級的目錄）下所有合格檔案都會被尋找到。例如：

      • /apsara/nuwa/**/*.log表示/apsara/nuwa目錄（包含該目錄的遞迴子目錄）中尾碼名為.log的檔案。

      • /var/logs/app_*/**/*.log表示/var/logs目錄下所有符合app_*格式的目錄（包含該目錄的遞迴子目錄）中尾碼名為.log的檔案。

      • /var/log/nginx/**/access*表示/var/log/nginx目錄（包含該目錄的遞迴子目錄）中以access開頭的檔案。

      最大目錄監控深度

      設定日誌目錄被監控的最大深度，即檔案路徑中萬用字元**匹配的最大目錄深度。0代表只監控本層目錄。

      檔案編碼

      選擇記錄檔的編碼格式。

      首次採集大小

      配置首次生效時，匹配檔案的起始採集位置距離檔案結尾的大小。首次採集大小設定值為1024 KB。

      • 首次採集時，如果檔案小於1024 KB，則從檔案內容起始位置開始採集。

      • 首次採集時，如果檔案大於1024 KB，則從距離檔案末尾1024 KB的位置開始採集。

      您可以通過此處修改首次採集大小，取值範圍為0~10485760，單位為KB。

      採集黑名單

      開啟採集黑名單開關後，可進行黑名單配置，即可在採集時忽略指定的目錄或檔案。支援完整匹配和萬用字元匹配目錄和檔案名稱。其中，萬用字元只支援星號（*）和半形問號（?）。

      重要

      • 如果您在配置檔案路徑時使用了萬用字元，但又需要過濾掉其中部分路徑，則需在採集黑名單中填寫對應的完整路徑來保證黑名單配置生效。

        例如您配置檔案路徑為/home/admin/app*/log/*.log，但要過濾/home/admin/app1*目錄下的所有子目錄，則需選擇目錄黑名單，配置目錄為/home/admin/app1*/**。如果配置為/home/admin/app1*，黑名單不會生效。

      • 匹配黑名單過程存在計算開銷，建議黑名單條目數控制在10條內。

      • 目錄路徑不能以正斜線（/）結尾，例如將設定路徑為/home/admin/dir1/，目錄黑名單不會生效。

      支援按照檔案路徑黑名單、檔案黑名單、目錄黑名單設定，詳細說明如下：

      檔案路徑黑名單

      • 選擇檔案路徑黑名單，配置路徑為/home/admin/private*.log，則表示在採集時忽略/home/admin/目錄下所有以private開頭，以.log結尾的檔案。

      • 選擇檔案路徑黑名單，配置路徑為/home/admin/private*/*_inner.log，則表示在採集時忽略/home/admin/目錄下以private開頭的目錄內，以_inner.log結尾的檔案。例如/home/admin/private/app_inner.log檔案被忽略，/home/admin/private/app.log檔案被採集。

      檔案黑名單

      選擇檔案黑名單，設定檔名為app_inner.log，則表示採集時忽略所有名為app_inner.log的檔案。

      目錄黑名單

      • 選擇目錄黑名單，配置目錄為/home/admin/dir1，則表示在採集時忽略/home/admin/dir1目錄下的所有檔案。

      • 選擇目錄黑名單，配置目錄為/home/admin/dir*，則表示在採集時忽略/home/admin/目錄下所有以dir開頭的子目錄下的檔案。

      • 選擇目錄黑名單，配置目錄為/home/admin/*/dir，則表示在採集時忽略/home/admin/目錄下二級目錄名為dir的子目錄下的所有檔案。例如/home/admin/a/dir目錄下的檔案被忽略，/home/admin/a/b/dir目錄下的檔案被採集。

      允許檔案多次採集

      預設情況下，一個記錄檔只能匹配一個Logtail配置。如果檔案中的日誌需要被採集多份，需要開啟允許檔案多次採集開關。

      進階參數

      其它可選的與檔案輸入外掛程式相關的進階功能參數，請參見建立Logtail流水線配置。

      處理配置

      配置項

      說明

      日誌範例

      待採集日誌的範例，請務必使用實際情境的日誌。日誌範例可協助您配置Tlog相關參數，降低配置難度。支援添加多條範例，總長度不超過1500個字元。

      [2023-10-01T10:30:01,000] [INFO] java.lang.Exception: exception happened
    at TestPrintStackTrace.f(TestPrintStackTrace.java:3)
    at TestPrintStackTrace.g(TestPrintStackTrace.java:7)
    at TestPrintStackTrace.main(TestPrintStackTrace.java:16)

      多行模式

      • 多行日誌的類型：多行日誌是指每條日誌分布在連續的多行中，需要從日誌內容中區分出每一條日誌。

        • 自訂：通過行首Regex區分每一條日誌。

        • 多行JSON：每個JSON對象被展開為多行，例如：

          {
  "name": "John Doe",
  "age": 30,
  "address": {
    "city": "New York",
    "country": "USA"
  }
}

      • 切分失敗處理方式：

        Exception in thread "main" java.lang.NullPointerException
    at com.example.MyClass.methodA(MyClass.java:12)
    at com.example.MyClass.methodB(MyClass.java:34)
    at com.example.MyClass.main(MyClass.java:½0)

        對於以上日誌內容，如果Log Service切分失敗：

        • 丟棄：直接丟棄這段日誌。

        • 保留單行：將每行日誌文本單獨保留為一條日誌，保留為一共四條日誌。

      處理模式

      處理模式選擇SPL。

      SPL語句

      SPL語句具體請參考 SPL文法。解析日誌前，日誌預設存在content欄位中。

      逾時時間

      SPL語句執行一次的最大時間。

    在建立Logtail配置時添加SPL

    1. 登入Log Service控制台。

    2. 在快速數據接入對話方塊的自建開源/商業軟體頁簽下，選擇包含文本日誌尾碼的入口。

      說明

      目前SPL採集支援文本日誌採集，其他資料接入（Kubernetes - 標準輸出、Docker標準輸出等）暫不支援控制台配置。

      在 快速接入資料 地區，單擊 接入資料 進入快速資料接入對話方塊。

    3. 在選擇日誌空間頁面，按照選擇目標Project和Logstore，單擊下一步。

      image

    4. 在機器組配置頁面，配置機器組。

      1. 根據實際需求，選擇使用情境和安裝環境。

        重要

        無論是否已有機器組，都必鬚根據實際需求正確選擇使用情境和安裝環境，這將影響後續的頁面配置。

      2. 確認目標機器組已在應用機器組地區，單擊下一步。

        已有機器組

        從源機器組列表選擇目標機器組。

        image

        沒有可用機器組

        單擊建立機器組，在建立機器組面板設定相關參數。機器組標識分為IP地址和使用者自訂標識，更多資訊請參見建立使用者自訂標識機器組（推薦）或建立IP地址機器組。

        重要

        建立機器組後立刻應用，可能因為串連未生效，導致心跳為FAIL，您可單擊自動重試。如果還未解決，請參見Logtail機器組無心跳進行排查。

    5. 建立Logtail配置，單擊下一步，建立Logtail配置。全域配置、輸入配置和處理外掛程式相同，處理配置中處理模式選擇SPL。

      • 全域配置

        配置項

        說明

        配置名稱

        Logtail配置名稱，在其所屬Project內必須唯一。建立Logtail配置成功後，無法修改其名稱。

        日誌主題類型

        選擇日誌主題（Topic）的產生方式。更多資訊，請參見日誌主題。

        • 機器組Topic：設定為機器組的Topic屬性，用於明確區分不同機器組產生的日誌。

        • 檔案路徑提取：設定為檔案路徑正則，則需要設定自訂正則，用Regex從路徑裡提取一部分內容作為Topic。用於區分不同源產生的日誌。

        • 自訂：自訂日誌主題。

        進階參數

        其它可選的與配置全域相關的進階功能參數，請參見建立Logtail流水線配置。

      • 輸入配置

        配置項

        說明

        檔案路徑

        根據日誌在主機（例如ECS）上的位置，設定日誌目錄和檔案名稱。

        • 如果目標主機是Linux系統，則日誌路徑必須以正斜線（/）開頭，例如/apsara/nuwa/**/app.Log。

        • 如果目標主機是Windows系統，則日誌路徑必須以盤符開頭，例如C:\Program Files\Intel\**\*.Log。

        目錄名和檔案名稱均支援完整模式和萬用字元模式，檔案名稱規則請參見Wildcard matching。其中，日誌路徑萬用字元只支援星號（*）和半形問號（?）。

        記錄檔尋找模式為多層目錄匹配，即合格指定目錄（包含所有層級的目錄）下所有合格檔案都會被尋找到。例如：

        • /apsara/nuwa/**/*.log表示/apsara/nuwa目錄（包含該目錄的遞迴子目錄）中尾碼名為.log的檔案。

        • /var/logs/app_*/**/*.log表示/var/logs目錄下所有符合app_*格式的目錄（包含該目錄的遞迴子目錄）中尾碼名為.log的檔案。

        • /var/log/nginx/**/access*表示/var/log/nginx目錄（包含該目錄的遞迴子目錄）中以access開頭的檔案。

        最大目錄監控深度

        設定日誌目錄被監控的最大深度，即檔案路徑中萬用字元**匹配的最大目錄深度。0代表只監控本層目錄。

        檔案編碼

        選擇記錄檔的編碼格式。

        首次採集大小

        配置首次生效時，匹配檔案的起始採集位置距離檔案結尾的大小。首次採集大小設定值為1024 KB。

        • 首次採集時，如果檔案小於1024 KB，則從檔案內容起始位置開始採集。

        • 首次採集時，如果檔案大於1024 KB，則從距離檔案末尾1024 KB的位置開始採集。

        您可以通過此處修改首次採集大小，取值範圍為0~10485760，單位為KB。

        採集黑名單

        開啟採集黑名單開關後，可進行黑名單配置，即可在採集時忽略指定的目錄或檔案。支援完整匹配和萬用字元匹配目錄和檔案名稱。其中，萬用字元只支援星號（*）和半形問號（?）。

        重要

        • 如果您在配置檔案路徑時使用了萬用字元，但又需要過濾掉其中部分路徑，則需在採集黑名單中填寫對應的完整路徑來保證黑名單配置生效。

          例如您配置檔案路徑為/home/admin/app*/log/*.log，但要過濾/home/admin/app1*目錄下的所有子目錄，則需選擇目錄黑名單，配置目錄為/home/admin/app1*/**。如果配置為/home/admin/app1*，黑名單不會生效。

        • 匹配黑名單過程存在計算開銷，建議黑名單條目數控制在10條內。

        • 目錄路徑不能以正斜線（/）結尾，例如將設定路徑為/home/admin/dir1/，目錄黑名單不會生效。

        支援按照檔案路徑黑名單、檔案黑名單、目錄黑名單設定，詳細說明如下：

        檔案路徑黑名單

        • 選擇檔案路徑黑名單，配置路徑為/home/admin/private*.log，則表示在採集時忽略/home/admin/目錄下所有以private開頭，以.log結尾的檔案。

        • 選擇檔案路徑黑名單，配置路徑為/home/admin/private*/*_inner.log，則表示在採集時忽略/home/admin/目錄下以private開頭的目錄內，以_inner.log結尾的檔案。例如/home/admin/private/app_inner.log檔案被忽略，/home/admin/private/app.log檔案被採集。

        檔案黑名單

        選擇檔案黑名單，設定檔名為app_inner.log，則表示採集時忽略所有名為app_inner.log的檔案。

        目錄黑名單

        • 選擇目錄黑名單，配置目錄為/home/admin/dir1，則表示在採集時忽略/home/admin/dir1目錄下的所有檔案。

        • 選擇目錄黑名單，配置目錄為/home/admin/dir*，則表示在採集時忽略/home/admin/目錄下所有以dir開頭的子目錄下的檔案。

        • 選擇目錄黑名單，配置目錄為/home/admin/*/dir，則表示在採集時忽略/home/admin/目錄下二級目錄名為dir的子目錄下的所有檔案。例如/home/admin/a/dir目錄下的檔案被忽略，/home/admin/a/b/dir目錄下的檔案被採集。

        允許檔案多次採集

        預設情況下，一個記錄檔只能匹配一個Logtail配置。如果檔案中的日誌需要被採集多份，需要開啟允許檔案多次採集開關。

        進階參數

        其它可選的與檔案輸入外掛程式相關的進階功能參數，請參見建立Logtail流水線配置。

      • 處理配置

        配置項

        說明

        日誌範例

        待採集日誌的範例，請務必使用實際情境的日誌。日誌範例可協助您配置Tlog相關參數，降低配置難度。支援添加多條範例，總長度不超過1500個字元。

        [2023-10-01T10:30:01,000] [INFO] java.lang.Exception: exception happened
    at TestPrintStackTrace.f(TestPrintStackTrace.java:3)
    at TestPrintStackTrace.g(TestPrintStackTrace.java:7)
    at TestPrintStackTrace.main(TestPrintStackTrace.java:16)

        多行模式

        • 多行日誌的類型：多行日誌是指每條日誌分布在連續的多行中，需要從日誌內容中區分出每一條日誌。

          • 自訂：通過行首Regex區分每一條日誌。

          • 多行JSON：每個JSON對象被展開為多行，例如：

            {
  "name": "John Doe",
  "age": 30,
  "address": {
    "city": "New York",
    "country": "USA"
  }
}

        • 切分失敗處理方式：

          Exception in thread "main" java.lang.NullPointerException
    at com.example.MyClass.methodA(MyClass.java:12)
    at com.example.MyClass.methodB(MyClass.java:34)
    at com.example.MyClass.main(MyClass.java:½0)

          對於以上日誌內容，如果Log Service切分失敗：

          • 丟棄：直接丟棄這段日誌。

          • 保留單行：將每行日誌文本單獨保留為一條日誌，保留為一共四條日誌。

        處理模式

        處理模式選擇SPL。

        SPL語句

        SPL語句具體請參考 SPL文法。解析日誌前，日誌預設存在content欄位中。

        逾時時間

        SPL語句執行一次的最大時間。