時間處理類外掛程式 - Simple Log Service

時間處理類外掛程式用於解析、提取、標準化日誌時間。

外掛程式效果樣本

表格展示該原始日誌在分別使用時間解析外掛程式（原生）與不使用外掛程式的情況下，儲存到Log Service後的資料結構。

原始日誌	不使用外掛程式	使用時間解析外掛程式（原生）
`{"level":"INFO","timestamp":"2025-09-29T09:56:01+0800","cluster":"yilu-cluster-0728","message":"User logged in successfully","userId":"user-123"}`	Content："{"level":"INFO","timestamp":"2025-09-29T09:56:01+0800","cluster":"yilu-cluster-0728","message":"User logged in successfully","userId":"user-123"}"

時間處理類外掛程式概覽

Log Service提供以下多種類型的時間處理類外掛程式，請按需要進行選擇。

外掛程式名稱	類型	功能說明
時間解析	原生	解析並標準化日誌中的時間欄位。
提取日誌時間	拓展	解析原始時間欄位並可設為日誌時間戳記。

功能入口

當您需要使用Logtail外掛程式處理日誌時，您可以在建立或修改Logtail配置時，添加外掛程式。具體操作，請參見原生與拓展處理外掛程式使用說明。

原生外掛程式與拓展外掛程式的區別

原生外掛程式：C++實現，效能更強。

拓展外掛程式：Go實現，生態豐富且靈活，當業務日誌過於複雜，無法使用原生外掛程式處理時，可以考慮使用拓展外掛程式。

拓展外掛程式效能限制
- 使用拓展外掛程式進行Tlog時，LoongCollector會消耗更多的資源（以CPU為主），如有需求可以調整LoongCollector參數配置進行日誌傳輸延時過長最佳化。
- 當未經處理資料量的產生速度超過5 MB/s時，不建議使用過於複雜的外掛程式組合來處理日誌，可以使用拓展外掛程式進行簡單處理，再通過資料加工概述完成進一步處理。
日誌採集限制
- 拓展外掛程式對文本日誌的處理採用行模式，即檔案層級的中繼資料（例如__tag__:__path__、__topic__等）會被存放到每一條日誌中。
- 添加拓展外掛程式後會影響和Tag相關的功能：
  - 上下文查詢和LiveTail功能不可用。如果要使用這些功能，需要額外添加aggregators配置。
  - __topic__欄位會被重新命名為__log_topic__。如果添加了aggregators配置，日誌中將同時存在__topic__欄位和__log_topic__欄位。如果您不需要__log_topic__欄位，可使用丟棄欄位外掛程式刪除該欄位。
  - __tag__:__path__等欄位不再具備原生欄位索引，需要建立索引。

時間解析外掛程式（原生）

時間解析外掛程式用於解析日誌的時間欄位，並將解析結果設定為日誌的__time__欄位。

配置說明

參數名稱	說明
原始欄位	解析日誌前，用於存放日誌內容的原始欄位，預設值為content。
時間格式	根據日誌中的時間內容設定對應的時間格式。例如日誌中的時間為10/Sep/2023:12:36:49，對應的時間轉換格式為%d/%b/%Y:%H:%M:%S。
時區	選擇日誌時間欄位所在的時區。如果不選擇，則預設使用機器時區，即使用Logtail進程所在環境的時區。

常見日誌時間格式

Logtail支援的常見日誌時間格式如下表所示。

說明

預設情況下，Simple Log Service中的日誌時間戳記精確到秒，所以時間格式只需配置到秒，無需配置毫秒、微秒等資訊。
如果原始日誌中的時間欄位包含毫秒、微秒或納秒級精度，且需在Log Service中保留該精度，請參見日誌採集支援納秒精度時間戳記。
在Linux伺服器中，Logtail支援strftime函數提供的所有時間格式。即能被strftime函數格式化的日誌時間字串都能被Logtail解析並使用。

時間格式	說明	樣本
%a	星期的縮寫。	Fri
%A	星期的全稱。	Friday
%b	月份的縮寫。	Jan
%B	月份的全稱。	January
%d	每月第幾天，十進位，範圍為01~31。	07, 31
%f	秒的小數部分（毫秒、微秒或納秒）	123
%h	月份的縮寫，等同於%b。	Jan
%H	小時，24小時制。	22
%I	小時，12小時制。	11
%m	月份，十進位，範圍為01~12。	08
%M	分鐘，十進位，範圍為00~59。	59
%n	分行符號。	分行符號
%p	AM或PM。	AM、PM
%r	12小時制的時間組合，等同於%I:%M:%S %p。	11:59:59 AM
%R	小時和分鐘組合，等同於%H:%M。	23:59
%S	秒數，十進位，範圍為00~59。	59
%t	Tab符號，定位字元。	無
%y	年份，十進位，不帶世紀，範圍為00~99。	04、98
%Y	年份，十進位。	2004、1998
%C	世紀，十進位，範圍為00~99。	16
%e	每月第幾天，十進位，範圍為1~31。如果是個位元字，前面需要加空格。	7、31
%j	一年中的天數，十進位，範圍為001~366。	365
%u	星期幾，十進位，範圍為1~7，1表示周一。	2
%U	每年的第幾周，星期天是一周的開始，範圍為00~53。	23
%V	每年的第幾周，星期一是一周的開始，範圍為01~53。如果一月份剛開始的一周>=4天，則認為是第1周，否則認為下一個星期是第1周。	24
%w	星期幾，十進位，範圍為0~6，0代表周日。	5
%W	每年的第幾周，星期一是一周的開始，範圍為00~53。	23
%c	標準的日期和時間。	Tue Nov 20 14:12:58 2020
%x	標準的日期，不帶時間。	Tue Nov 20 2020
%X	標準的時間，不帶日期。	11:59:59
%s	Unix時間戳記。	1476187251

樣本

常見的時間標準、樣本及對應的時間運算式如下所示。

樣本	時間運算式	時間標準
2017-12-11 15:05:07	%Y-%m-%d %H:%M:%S	自訂
[2017-12-11 15:05:07.012]	[%Y-%m-%d %H:%M:%S	自訂
2017-12-11 15:05:07.123	%Y-%m-%d %H:%M:%S.%f	自訂
02 Jan 06 15:04 MST	%d %b %y %H:%M	RFC822
02 Jan 06 15:04 -0700	%d %b %y %H:%M	RFC822Z
Monday, 02-Jan-06 15:04:05 MST	%A, %d-%b-%y %H:%M:%S	RFC850
Mon, 02 Jan 2006 15:04:05 MST	%A, %d %b %Y %H:%M:%S	RFC1123
2006-01-02T15:04:05Z07:00	%Y-%m-%dT%H:%M:%S	RFC3339
2006-01-02T15:04:05.999999999Z07:00	%Y-%m-%dT%H:%M:%S	RFC3339Nano
1637843406	%s	自訂
1637843406123	%s	自訂（Simple Log Service以秒級精度處理）

提取日誌時間外掛程式（拓展）

使用processor_gotime外掛程式或processor_strptime外掛程式解析原始日誌中的時間欄位。此處介紹兩種外掛程式的參數說明和配置樣本。

說明

如果原始日誌中的時間欄位包含毫秒、微秒或納秒級精度，且需在Log Service中保留該精度，請參見日誌採集支援納秒精度時間戳記。

Go語言時間格式（`processor_gotime`）

processor_gotime外掛程式使用Go語言時間格式解析原始日誌中的時間欄位，並支援將解析結果設定為Log Service中的日誌時間。

重要

Logtail 0.16.28及以上版本支援processor_gotime外掛程式。
表單配置方式：採集文本日誌和容器標準輸出時可用。
JSON配置方式：採集文本日誌時不可用。

表單配置方式

參數說明

配置處理外掛程式類型為提取日誌時間（Go語言時間格式）。

相關參數說明如下表所示。

參數	說明
原始時間欄位	原始欄位名。
原始時間格式	原始時間的格式。
原始時間時區	原始時間的時區。選擇機器時區時，表示Logtail所在主機或容器的時區。
結果時間欄位	解析後的目標欄位，該欄位不支援設定為`__time__`。
結果時間格式	解析後的時間格式。
自訂結果時間時區	解析後的時區。選擇機器時區時，表示原生時區。
進階參數>設為日誌時間	選中該選項後，系統會將解析後的時間設定為日誌時間。
進階參數>保留原始欄位	選中該選項後，解析後的日誌中將保留原始欄位。
進階參數>原始欄位缺失報錯	選中該選項後，如果原始日誌中無您所指定的原始欄位，系統將報錯。
進階參數>提取失敗報錯	選中該選項後，如果提取日誌時間失敗，系統將報錯。

樣本
原始時間（s_key欄位）的格式為2006-01-02 15:04:05（東八區），現將原始時間解析為2006/01/02 15:04:05（東九區）格式，添加到d_key欄位中，並設定解析結果為Log Service中的日誌時間。
- 原始日誌
```
"s_key":"2022-07-05 19:28:01"
```
- Logtail外掛程式處理配置
- 處理結果
```
"s_key":"2022-07-05 19:28:01"
"d_key":"2022/07/05 20:28:01"
```

JSON配置方式

參數說明

配置type為processor_gotime，detail說明如下表所示。

參數	類型	是否必選	說明
SourceKey	String	是	原始欄位名。
SourceFormat	String	是	原始時間的格式。
SourceLocation	Int	是	原始時間的時區。參數值為空白時，表示Logtail所在主機或容器的時區。
DestKey	String	是	解析後的目標欄位，該欄位不支援設定為`__time__`。
DestFormat	String	是	解析後的時間格式。
DestLocation	Int	否	解析後的時區。參數值為空白時，表示本機時區。
SetTime	Boolean	否	是否將解析後的時間設定為日誌時間。 true（預設值）：是 false：否
KeepSource	Boolean	否	被解析後的日誌中是否保留原始欄位。 true（預設值）：保留 false：不保留
NoKeyError	Boolean	否	原始日誌中無您所指定的原始欄位時，系統是否報錯。 true（預設值）：報錯 false：不報錯
AlarmIfFail	Boolean	否	提取日誌時間失敗，系統是否報錯。 true（預設值）：報錯 false：不報錯

樣本

原始時間（s_key欄位）的格式為2006-01-02 15:04:05（東八區），現將原始時間解析為2006/01/02 15:04:05（東九區）格式，添加到d_key欄位中，並設定解析結果為Log Service中的日誌時間。

原始日誌
```
"s_key":"2019-07-05 19:28:01"
```

Logtail外掛程式處理配置

{
  "processors":[
    {
      "type":"processor_gotime",
      "detail": {
        "SourceKey": "s_key",
        "SourceFormat":"2006-01-02 15:04:05",
        "SourceLocation":8,
        "DestKey":"d_key",
        "DestFormat":"2006/01/02 15:04:05",
        "DestLocation":9,
        "SetTime": true,
        "KeepSource": true,
        "NoKeyError": true,
        "AlarmIfFail": true
      }
    }
  ]
}

處理結果

"s_key":"2019-07-05 19:28:01"
"d_key":"2019/07/05 20:28:01"（）

strptime時間格式（`processor_strptime`）

processor_strptime外掛程式使用Linux strptime時間格式解析日誌中的時間欄位，並支援將解析結果設定為日誌時間。

重要

Logtail 0.16.28及以上版本支援processor_strptime外掛程式。

表單配置方式

參數說明

配置處理器類型為提取日誌時間（strptime時間格式），相關參數說明如下表所示。

參數	說明
原始欄位	原始欄位名。
原始時間格式	原始時間的格式。
保留原始欄位	選中該選項後，被解析後的日誌中將保留原始欄位。
提取失敗報錯	選中該選項後，如果提取日誌時間失敗，系統將報錯。
進行時間位移	選中該選項後，您可以設定時間位移秒數。
時間位移秒數	時間位移秒數。例如28800表示東八區，-3600代表西一區。

配置樣本
將%Y/%m/%d %H:%M:%S格式的原始時間（log_time欄位的值）解析為對應的日誌時間，時區使用機器所在時區。假設時區為東八區。
- 原始日誌
```
"log_time":"2022/01/02 12:59:59"
```
- Logtail外掛程式處理配置
- 處理結果
```
"log_time":"2022/01/02 12:59:59"
Log.Time = 1451710799
```

常見的時間運算式

說明

processor_strptime外掛程式支援%f格式解析，表示秒的小數部分，最高精度為納秒。

樣本	時間運算式
2016/01/02 12:59:59	%Y/%m/%d %H:%M:%S
2016/01/02 12:59:59.1	%Y/%m/%d %H:%M:%S.%f
2016/01/02 12:59:59.987654321 +0700 (UTC)	%Y/%m/%d %H:%M:%S.%f %z (%Z)
2016/Jan/02 12:59:59,123456	%Y/%b/%d %H:%M:%S,%f
2019-07-15T04:16:47:123Z	%Y-%m-%dT%H:%M:%S:%f

JSON配置方式

參數說明

配置type為processor_strptime，detail說明如下表所示。

參數	類型	是否必選	說明
SourceKey	String	是	原始欄位名。
Format	String	是	原始時間的格式。
AdjustUTCOffset	Boolean	否	是否調整時區。 true：是。 false（預設值）：否
UTCOffset	Int	否	用於調整的時區位移秒數。例如28800表示東八區。
AlarmIfFail	Boolean	否	提取日誌失敗時，系統是否報錯。 true（預設值）：報錯。 false：不報錯。
KeepSource	Boolean	否	被解析後的日誌中，是否保留原始欄位。 true（預設值）：保留。 false：不保留。
EnablePreciseTimestamp	Boolean	否	是否提取高精度時間。 true：是。 false（預設值）：否。設定為true後，該外掛程式會將SourceKey參數對應的欄位值解析為毫秒層級的時間戳記，並存入PreciseTimestampKey參照中對應的欄位。重要設定該參數為true前，請確保SourceKey參數對應的欄位值（原始時間）支援相應的時間精度（ms、us或ns）。僅Logtail 1.0.32及以上版本支援。
PreciseTimestampKey	String	否	儲存高精度時間戳記的欄位。預設值為precise_timestamp欄位。
PreciseTimestampUnit	String	否	高精度時間戳記的單位。預設值為ms。取值包括ms（毫秒）、us（微秒）、ns（納秒）。

樣本

將%Y/%m/%d %H:%M:%S格式的原始時間（log_time欄位的值）解析為對應的日誌時間，時區使用機器所在時區。

樣本1：假設時區為東八區。

原始日誌
```
"log_time":"2016/01/02 12:59:59"
```

Logtail外掛程式處理配置

{
  "processors":[
    {
      "type":"processor_strptime",
      "detail": {
        "SourceKey": "log_time",
        "Format": "%Y/%m/%d %H:%M:%S"
      }
    }
  ]
}

處理結果

"log_time":"2016/01/02 12:59:59"
Log.Time = 1451710799

樣本2：假設時區為東七區。

原始日誌
```
"log_time":"2016/01/02 12:59:59"
```

Logtail外掛程式處理配置

{
  "processors":[
    {
      "type":"processor_strptime",
      "detail": {
        "SourceKey": "log_time",
        "Format": "%Y/%m/%d %H:%M:%S",
        "AdjustUTCOffset": true,
        "UTCOffset": 25200
      }
    }
  ]
}

處理結果

"log_time":"2016/01/02 12:59:59"
Log.Time = 1451714399

樣本3：假設時區為東七區。

原始日誌
```
"log_time":"2016/01/02 12:59:59.123"
```

Logtail外掛程式處理配置

{
  "processors":[
    {
      "type":"processor_strptime",
      "detail": {
        "SourceKey": "log_time",
        "Format": "%Y/%m/%d %H:%M:%S.%f",
        "EnablePreciseTimestamp": true
      }
    }
  ]
}

處理結果

"log_time":"2016/01/02 12:59:59.123"
"precise_timestamp": 1451714399123
Log.Time = 1451714399

常見的時間運算式

說明

processor_strptime外掛程式支援%f格式解析，表示秒的小數部分，最高精度為納秒。

樣本	時間運算式
2016/01/02 12:59:59	%Y/%m/%d %H:%M:%S
2016/01/02 12:59:59.1	%Y/%m/%d %H:%M:%S.%f
2016/01/02 12:59:59.987654321 +0700 (UTC)	%Y/%m/%d %H:%M:%S.%f %z (%Z)
2016/Jan/02 12:59:59,123456	%Y/%b/%d %H:%M:%S,%f
2019-07-15T04:16:47:123Z	%Y-%m-%dT%H:%M:%S:%f

Simple Log Service：時間處理類外掛程式

外掛程式效果樣本

時間處理類外掛程式概覽

功能入口

原生外掛程式與拓展外掛程式的區別

時間解析外掛程式（原生）

配置說明

常見日誌時間格式

樣本

提取日誌時間外掛程式（拓展）

Go語言時間格式（`processor_gotime`）

表單配置方式

JSON配置方式

strptime時間格式（`processor_strptime`）

表單配置方式

JSON配置方式

相關文檔

外掛程式效果樣本

時間處理類外掛程式概覽

功能入口

原生外掛程式與拓展外掛程式的區別

時間解析外掛程式（原生）

配置說明

常見日誌時間格式

樣本

提取日誌時間外掛程式（拓展）

Go語言時間格式（processor_gotime）

表單配置方式

JSON配置方式

strptime時間格式（processor_strptime）

表單配置方式

JSON配置方式

相關文檔

Go語言時間格式（`processor_gotime`）

strptime時間格式（`processor_strptime`）