通過建立Logtail配置實現定製化採集策略 - Simple Log Service

Logtail配置是Logtail採集日誌的策略集合。通過在建立Logtail配置時設定資料來源、採集模式等參數，實現定製化的採集策略。本文介紹API模式下Logtail配置相關的參數說明。

Logtail配置基礎參數說明

參數名稱	資料類型	是否必填	樣本值	描述
configName	string	是	config-sample	Logtail配置的名稱，在其所屬Project內必須唯一。建立Logtail配置成功後，無法修改其名稱。命名規則如下：只能包括小寫字母、數字、短劃線（-）和底線（_）。必須以小寫字母或者數字開頭和結尾。長度必須在2~128字元之間。
inputType	string	是	file	日誌輸入的方式。可選值如下： plugin：通過Logtail外掛程式採集MySQL Binlog等日誌。 file：通過固定模式（正則模式、分隔字元模式等）採集文字檔中的日誌。
inputDetail	JSON object	是	無	日誌輸入的相關配置。更多資訊，請參見inputDetail參數說明。
outputType	string	是	LogService	日誌輸出的方式，只支援LogService，即只支援將資料上傳到Log Service。
outputDetail	JSON object	是	無	日誌輸出的相關配置。更多資訊，請參見outputDetail參數說明。
logSample	string	否	無	日誌範例。說明日誌範例長度必須小於1500位元組。

inputDetail參數說明

基礎參數

參數名稱	資料類型	是否必填	樣本值	描述
filterKey	array	否	["ip"]	用於過濾日誌的欄位。只有該欄位的值滿足filterRegex參數中設定的Regex時，對應的日誌才會被採集。
filterRegex	array	否	["^10.*"]	與filterKey對應的Regex。filterRegex中的元素個數和filterKey中的元素個數必須相同。
shardHashKey	array	否	["__source__"]	資料寫入模式。預設按照負載平衡模式寫入資料。更多資訊，請參見負載平衡模式。配置該參數後，按照Shard模式寫入。更多資訊，請參見Shard模式。支援__source__欄位。
enableRawLog	boolean	否	false	是否上傳原始日誌。可選值如下： true：上傳原始日誌。 false（預設）：不上傳原始日誌。
sensitive_keys	array	否	無	脫敏功能。更多資訊，請參見sensitive_keys參數說明。
mergeType	string	否	topic	彙總方式。可選值如下： topic（預設）：根據Topic彙總。 logstore：根據Logstore彙總。
delayAlarmBytes	int	否	209715200	採集進度落後的警示閾值。預設值：209715200，即200 MB。
adjustTimezone	boolean	否	false	是否調整日誌時區，僅在配置時間解析（例如配置了timeFormat參數）的情況下使用。
logTimezone	string	否	GMT+08:00	時區位移量，格式為GMT+HH:MM（東區）、GMT-HH:MM（西區）。例如日誌時間為東八區，則該值為GMT+08:00。
advanced	JSON object	否	無	擴充功能。更多資訊，請參見advanced參數說明。

sensitive_keys參數

參數說明

參數名稱	資料類型	是否必填	樣本值	描述
key	string	是	content	日誌欄位名稱。
type	string	是	const	脫敏方式。可選值如下： const：將敏感內容替換成const欄位取值內容。 md5：將敏感內容替換為其對應的MD5值。
regex_begin	string	是	'password':'	敏感內容首碼的Regex，用於尋找敏感內容。使用RE2文法。更多資訊，請參見RE2文法。
regex_content	string	是	[^']*	敏感內容的Regex，使用RE2文法。更多資訊，請參見RE2文法。
all	boolean	是	true	是否替換該欄位中所有的敏感內容。可選值如下： true（推薦）：替換。 false：只替換欄位中匹配Regex的第一部分內容。
const	string	否	"********"	當type設定為const時，必須配置。

配置樣本
例如日誌中content欄位的值為[{'account':'1812213231432969','password':'04a23f38'}, {'account':'1812213685634','password':'123a'}]，現需要將password部分替換為********，則設定sensitive_keys為如下內容。
```
sensitive_keys = [{"all": true,
"const": "********",
"regex_content": "[^']*",
"regex_begin": "'password':'",
"type": "const",
"key": "content"}]                    
```

日誌範例

[{'account':'1812213231432969','password':'********'}, {'account':'1812213685634','password':'********'}]

advanced參數

參數名稱	資料類型	是否必填	樣本	描述
enable_root_path_collection	boolean	否	false	是否允許採集Windows根目錄（例如D:\log*）中的資料。 true：允許。 false（預設）：不允許。重要本配置屬於全域參數，即您在一個Logtail採集配置中開啟此功能後，在Logtail重啟前，伺服器上所有的Logtail採集配置都允許採集根目錄。僅支援Windows Logtail 1.0.0.22及以上版本。
exactly_once_concurrency	int	否	1	是否啟用ExactlyOnce寫入功能。ExactlyOnce寫入功能用於指定單個檔案允許的發送並發數。取值範圍：0~512。更多資訊，請參見附錄：ExactlyOnce寫入功能說明。可選值如下： 0：不啟用ExactlyOnce寫入功能。其他值：開啟ExactlyOnce寫入功能，並指定單個檔案允許的發送並發數。重要此參數值過大會增加記憶體和磁碟開銷。請根據本地的寫入流量評估參數值。 Logtail本地會進行隨機化處理，即使此參數值小於Log Service端的Shard數量，也能保證寫入均衡，不需要完全對齊。配置該參數後，只對新檔案生效。僅支援Logtail 1.0.21及以上版本。
enable_log_position_meta	boolean	否	true	是否在日誌中添加該日誌所屬原始檔案的中繼資料資訊，即新增__tag__:__inode__欄位和__file_offset__欄位。可選值如下： true：添加。 false：不添加。說明僅支援Logtail 1.0.21及以上版本。
specified_year	uint	否	0	當原始日誌的時間缺少年份資訊時，您可以設定該參數，使用目前時間中的年份或指定年份補全日誌時間。可選值如下： 0：使用目前時間中的年份。具體年份（例如2020）：使用指定年份。說明僅支援Logtail 1.0.21及以上版本。
force_multiconfig	boolean	否	false	是否允許該Logtail配置採集其他Logtail配置已匹配的檔案。預設值：false，表示不允許。適用於檔案多寫情境，例如一個檔案通過兩個採集配置採集到不同的logstore。
raw_log_tag	string	否	__raw__	上傳原始日誌時，用於存放原始日誌的欄位，預設值：__raw__。
blacklist	object	否	無	採集黑名單配置。更多資訊，請參見blacklist參數說明。
tail_size_kb	int	否	1024	新檔案首次採集的大小。通過首次採集大小，可以確認首次採集的位置。Log Service預設首次採集大小為1024 KB，即：首次採集時，如果檔案小於1024 KB，則從檔案內容起始位置開始採集。首次採集時，如果檔案大於1024 KB，則從距離檔案末尾1024 KB的位置開始採集。您可以通過此處修改首次採集大小，取值範圍：0~10485760，單位：KB。
batch_send_interval	int	否	3	彙總發送周期。單位：秒，預設值：3。
max_rotate_queue_size	int	否	20	單檔案輪轉隊列的長度。預設值：20。
enable_precise_timestamp	boolean	否	false	是否提取高精度時間。如果未添加該參數，則預設使用false，表示不提取高精度時間。預設情況下，設定為true後，Logtail會將指定的時間欄位值解析為毫秒層級的時間戳記，並存入precise_timestamp_key參數對應的欄位。說明請確保已關閉Logtail採集配置中使用系統時間的開關。僅Logtail 1.0.32及以上版本支援。
precise_timestamp_key	string	否	"precise_timestamp"	儲存高精度時間戳記的欄位。如果未添加該參數，則預設為precise_timestamp欄位。
precise_timestamp_unit	string	否	"ms"	高精度時間戳記的單位。如果未添加該參數，則預設為ms。取值包括ms（毫秒）、us（微秒）、ns（納秒）。

其中，blacklist參數說明如下表所示。

參數名稱	資料類型	是否必填	樣本	描述
dir_blacklist	array	否	["/home/admin/dir1", "/home/admin/dir2*"]	目錄（絕對路徑）黑名單。支援使用萬用字元星號（*）匹配多個目錄。例如配置路徑為/home/admin/dir1，則表示在採集時忽略/home/admin/dir1目錄下的所有內容。
filename_blacklist	array	否	["app*.log", "password"]	檔案名稱黑名單，指定的檔案名稱在任何目錄下都不會被採集。支援使用萬用字元星號（*）匹配多個檔案名稱。
filepath_blacklist	array	否	["/home/admin/private*.log"]	檔案路徑（絕對路徑）黑名單。支援使用萬用字元星號（）匹配多個檔案。配置路徑為/home/admin/private.log，則表示在採集時忽略/home/admin/目錄下所有以private開頭，以.log結尾的檔案。

文本日誌的Logtail特有配置

基礎參數

參數名稱	資料類型	是否必填	樣本	描述
logType	string	是	common_reg_log	日誌的採集模式。具體說明如下： json_log：JSON模式。 common_reg_log：完整正則模式。 plugin：外掛程式模式。 delimiter_log：分隔字元模式。
logPath	string	是	/var/log/http/	記錄檔的路徑。
filePattern	string	是	access*.log	記錄檔名稱。
topicFormat	string	是	none	Topic產生方式。可選值如下： none：不組建記錄檔主題。 default：將記錄檔的路徑作為日誌主題。 group_topic：將應用該Logtail配置的機器組的Topic作為日誌主題。檔案路徑Regex：將記錄檔路徑的某一部分作為日誌主題。例如/var/log/(.*).log。更多資訊，請參見日誌主題。
timeFormat	string	否	%Y/%m/%d %H:%M:%S	日誌時間格式。更多資訊，請參見時間格式。
preserve	boolean	否	true	如果一個記錄檔在指定時間內沒有任何更新，則認為該檔案已逾時。可選值如下： true（預設）：永不逾時。 false：如果記錄檔在30分鐘內沒有更新，則認為已逾時，並不再監控該檔案。
preserveDepth	integer	否	1	當設定preserve為false時，需指定最大逾時目錄深度，取值範圍：1~3。
fileEncoding	string	否	utf8	記錄檔編碼格式，取值為utf8、gbk。
discardUnmatch	boolean	否	true	是否丟棄匹配失敗的日誌。可選值如下： true：丟棄匹配失敗的日誌。 false：不丟棄匹配失敗的日誌。
maxDepth	int	否	100	設定日誌目錄被監控的最大深度。取值範圍：0~1000，0代表只監控本層目錄。
delaySkipBytes	int	否	0	採集落後時是否丟棄落後資料的閾值。可選值如下： 0（預設）：不丟棄。其他值：當採集落後超過該值（例如1024 KB）時，則直接丟棄落後的資料。
dockerFile	boolean	否	false	採集的目標檔案是否為容器內檔案，預設為false。
dockerIncludeLabel	JSON object	否	無	容器Label白名單，用於指定待採集的容器。預設為空白，表示採集所有容器的日誌或標準輸出。如果您要設定容器Label白名單，那麼LabelKey必填，LabelValue可選填。如果LabelValue為空白，則容器Label中包含LabelKey的容器都匹配。如果LabelValue不為空白，則容器Label中包含LabelKey=LabelValue的容器才匹配。 LabelValue預設為字串匹配，即只有LabelValue和容器Label的值完全相同才會匹配。如果該值以`^`開頭並且以`$`結尾，則為正則匹配。例如設定LabelKey為`io.kubernetes.container.name`，設定LabelValue為`^(nginx\|cube)$`，表示可匹配名為nginx、cube的容器。說明請勿設定相同的LabelKey，如果重名只生效一個。多個白名單之間為或關係，即只要容器Label滿足任一白名單即可匹配。
dockerExcludeLabel	JSON object	否	無	容器Label黑名單，用於排除不採集的容器。預設為空白，表示不排除任何容器。如果您要設定容器Label黑名單，那麼LabelKey必填，LabelValue可選填。如果LabelValue為空白，則容器Label中包含LabelKey的容器都將被排除。如果LabelValue不為空白，則容器Label中包含LabelKey=LabelValue的容器才會被排除。 LabelValue預設為字串匹配，即只有LabelValue和容器Label的值完全相同才會匹配。如果該值以`^`開頭並且以`$`結尾，則為正則匹配。例如設定LabelKey為`io.kubernetes.container.name`，設定LabelValue為`^(nginx\|cube)$`，表示可匹配名為nginx、cube的容器。說明請勿設定相同的LabelKey，如果重名只生效一個。多個黑名單之間為或關係，即只要容器Label滿足任一黑名單對即可被排除。
dockerIncludeEnv	JSON object	否	無	環境變數白名單，用於指定待採集的容器。預設為空白，表示採集所有容器的日誌或標準輸出。如果您要設定環境變數白名單，那麼EnvKey必填，EnvValue可選填。如果EnvValue為空白，則容器環境變數中包含EnvKey的容器都匹配。如果EnvValue不為空白，則容器環境變數中包含EnvKey=EnvValue的容器才匹配。 EnvValue預設為字串匹配，即只有EnvValue和環境變數的值完全相同才會匹配。如果該值以`^`開頭並且以`$`結尾，則為正則匹配，例如設定EnvKey為`NGINX_SERVICE_PORT`，設定EnvValue為`^(80\|6379)$`，表示可匹配服務連接埠為80、6379的容器。說明多個白名單之間為或關係，即只要容器的環境變數滿足任一白名單即可匹配。
dockerExcludeEnv	JSON object	否	無	環境變數黑名單，用於排除不採集的容器。預設為空白，表示不排除任何容器。如果您要設定環境變數黑名單，那麼EnvKey必填，EnvValue可選填。如果EnvValue為空白，則容器環境變數中包含EnvKey的容器都將被排除。如果EnvValue不為空白，則容器環境變數中包含EnvKey=EnvValue的容器才會被排除。 EnvValue預設為字串匹配，即只有EnvValue和環境變數的值完全相同才會匹配。如果該值以`^`開頭並且以`$`結尾，則為正則匹配，例如設定EnvKey為`NGINX_SERVICE_PORT`，設定EnvValue為`^(80\|6379)$`，表示可匹配服務連接埠為80、6379的容器。說明多個黑名單之間為或關係，即只要容器的環境變數滿足任一索引值對即可被排除。

完整正則模式和極簡模式特有配置

參數說明

參數名稱	資料類型	是否必填	樣本值	描述
key	array	是	["content"]	欄位列表，用於為原始日誌內容配置欄位。
logBeginRegex	string	否	.*	行首Regex。
regex	string	否	(.*)	提取欄位的Regex。

配置樣本

{
    "configName": "logConfigName", 
    "outputType": "LogService", 
    "inputType": "file", 
    "inputDetail": {
        "logPath": "/logPath", 
        "filePattern": "*", 
        "logType": "common_reg_log", 
        "topicFormat": "default", 
        "discardUnmatch": false, 
        "enableRawLog": true, 
        "fileEncoding": "utf8", 
        "maxDepth": 10, 
        "key": [
            "content"
        ], 
        "logBeginRegex": ".*", 
        "regex": "(.*)"
    }, 
    "outputDetail": {
        "projectName": "test-project", 
        "logstoreName": "test-logstore"
    }
}

JSON模式特有配置

參數名稱	資料類型	是否必填	樣本值	描述
timeKey	string	否	time	指定時間欄位的key名稱。

分隔字元模式特有配置

參數說明

參數名稱	資料類型	是否必填	樣本值	描述
separator	string	否	,	根據您的日誌格式選擇正確的分隔字元。更多資訊，請參見使用分隔字元模式採集日誌。
quote	string	是	\	當日誌欄位內容中包含分隔字元時，需要指定引用符進行包裹，被引用符包裹的內容會被Log Service解析為一個完整欄位。請根據您的日誌格式選擇正確的引用符。更多資訊，請參見使用分隔字元模式採集日誌。
key	array	是	[ "ip", "time"]	欄位列表，用於為原始日誌內容配置欄位。
timeKey	string	是	time	指定key列表中的某個欄位為時間欄位。
autoExtend	boolean	否	true	如果日誌中分割出的欄位數少於配置的Key數量，是否上傳已解析的欄位。例如日誌為11\|22\|33\|44\|55，分隔字元為豎線（\|），日誌內容將被解析為11、22、33、44和55，為其分別設定Key為A、B、C、D和E。 true：採集日誌11\|22\|33\|55時，55會作為Key D的Value被上傳到Log Service。 false：採集日誌11\|22\|33\|55時，該條日誌會因欄位與Key不匹配而被丟棄。

配置樣本

{
    "configName": "logConfigName", 
    "logSample": "testlog", 
    "inputType": "file", 
    "outputType": "LogService", 
    "inputDetail": {
        "logPath": "/logPath", 
        "filePattern": "*", 
        "logType": "delimiter_log", 
        "topicFormat": "default", 
        "discardUnmatch": true, 
        "enableRawLog": true, 
        "fileEncoding": "utf8", 
        "maxDepth": 999, 
        "separator": ",", 
        "quote": "\"", 
        "key": [
            "ip", 
            "time"
        ], 
        "autoExtend": true
    }, 
    "outputDetail": {
        "projectName": "test-project", 
        "logstoreName": "test-logstore"
    }
}

Logtail外掛程式的特有配置

參數說明

外掛程式模式特有的配置說明如下表所示。

參數名稱	資料類型	是否必填	樣本值	描述
plugin	JSON object	是	無	使用Logtail外掛程式採集日誌時，需配置此參數。更多資訊，請參見使用Logtail外掛程式採集資料。

配置樣本

{
    "configName": "logConfigName", 
    "outputType": "LogService", 
    "inputType": "plugin",
    "inputDetail": {
        "plugin": {
            "inputs": [
                {
                    "detail": {
                        "ExcludeEnv": null, 
                        "ExcludeLabel": null, 
                        "IncludeEnv": null, 
                        "IncludeLabel": null, 
                        "Stderr": true, 
                        "Stdout": true
                    }, 
                    "type": "service_docker_stdout"
                }
            ]
        }
    }, 
    "outputDetail": {
        "projectName": "test-project", 
        "logstoreName": "test-logstore"
    }
}

outputDetail參數說明

用於配置日誌輸出的Project和Logstore。

參數名稱	資料類型	是否必填	樣本值	描述
projectName	string	是	my-project	Project名稱，必須為請求的Project名稱。
logstoreName	string	是	my-logstore	Logstore名稱。

附錄：ExactlyOnce寫入功能說明

開啟ExactlyOnce寫入功能後，Logtail會在本地磁碟記錄細粒度的Checkpoint資訊（檔案層級）。當出現進程異常、機器重啟等情況後，Logtail會在啟動時藉助Checkpoint資訊來確定每個檔案需要重新處理的範圍以及通過Log Service端對於重複資料的拒絕機制（遞增序號），可有效避免資料的重複發送。但該功能會佔用一定的磁碟寫入資源。相關限制如下：

Checkpoint資訊需要利用本地磁碟進行儲存。如果是磁碟原因導致Checkpoint無法記錄（磁碟滿）或者內容損壞（磁碟故障），可能導致恢複失敗。
Checkpoint僅記錄檔案的中繼資料資訊，不包含檔案資料。所以如果檔案本身被刪除或者修改，可能導致無法恢複。
ExactlyOnce寫入功能依賴Log Service端記錄的當前寫入序號，目前每個Shard僅支援10,000條記錄，在超出限制後，會產生記錄替換。因此為了保證可靠性，對於寫入同一個Logstore的活躍檔案數*Logtail執行個體數的結果不可超過9500（建議預留一定量）。
- 活躍檔案數：正在被讀取和發送的檔案數量。同一個邏輯檔案名稱的不同輪轉檔案會串列發送，它們僅被算作一個活躍檔案。
- Logtail執行個體數：即Logtail進程數。預設情況下每台機器就一個執行個體，即一般情況下等同於機器數。

出於效能考慮，預設寫入Checkpoint時不會調用sync落盤，所以如果機器重啟導致buffer資料來不及寫入磁碟時，可能導致Checkpoint丟失。您可以在Logtail啟動參數設定檔（/usr/local/ilogtail/ilogtail_config.json）中，增加"enable_checkpoint_sync_write": true,，開啟sync寫功能。具體操作，請參見設定Logtail啟動參數。