Logtail配置
Logtail配置是Logtail采集日志的策略集合。通過在創(chuàng)建Logtail配置時(shí)設(shè)置數(shù)據(jù)源、采集模式等參數(shù),實(shí)現(xiàn)定制化的采集策略。本文介紹API模式下Logtail配置相關(guān)的參數(shù)說明。
Logtail配置基礎(chǔ)參數(shù)說明
參數(shù)名稱 | 數(shù)據(jù)類型 | 是否必填 | 示例值 | 描述 |
configName | string | 是 | config-sample | Logtail配置的名稱,在其所屬Project內(nèi)必須唯一。創(chuàng)建Logtail配置成功后,無法修改其名稱。 命名規(guī)則如下:
|
inputType | string | 是 | file | 日志輸入的方式。可選值如下:
|
inputDetail | JSON object | 是 | 無 | 日志輸入的相關(guān)配置。更多信息,請參見inputDetail參數(shù)說明。 |
outputType | string | 是 | LogService | 日志輸出的方式,只支持LogService,即只支持將數(shù)據(jù)上傳到日志服務(wù)。 |
outputDetail | JSON object | 是 | 無 | 日志輸出的相關(guān)配置。更多信息,請參見outputDetail參數(shù)說明。 |
logSample | string | 否 | 無 | 日志樣例。 說明 日志樣例長度必須小于1500字節(jié)。 |
inputDetail參數(shù)說明
基礎(chǔ)參數(shù)
參數(shù)名稱 | 數(shù)據(jù)類型 | 是否必填 | 示例值 | 描述 |
filterKey | array | 否 | ["ip"] | 用于過濾日志的字段。只有該字段的值滿足filterRegex參數(shù)中設(shè)置的正則表達(dá)式時(shí),對應(yīng)的日志才會(huì)被采集。 |
filterRegex | array | 否 | ["^10.*"] | 與filterKey對應(yīng)的正則表達(dá)式。filterRegex中的元素個(gè)數(shù)和filterKey中的元素個(gè)數(shù)必須相同。 |
shardHashKey | array | 否 | ["__source__"] | 數(shù)據(jù)寫入模式。默認(rèn)按照負(fù)載均衡模式寫入數(shù)據(jù)。更多信息,請參見負(fù)載均衡模式。 配置該參數(shù)后,按照Shard模式寫入。更多信息,請參見Shard模式。支持__source__字段。 |
enableRawLog | boolean | 否 | false | 是否上傳原始日志。可選值如下:
|
sensitive_keys | array | 否 | 無 | 脫敏功能。更多信息,請參見sensitive_keys參數(shù)說明。 |
mergeType | string | 否 | topic | 聚合方式。可選值如下:
|
delayAlarmBytes | int | 否 | 209715200 | 采集進(jìn)度落后的告警閾值。默認(rèn)值:209715200,即200 MB。 |
adjustTimezone | boolean | 否 | false | 是否調(diào)整日志時(shí)區(qū),僅在配置時(shí)間解析(例如配置了timeFormat參數(shù))的情況下使用。 |
logTimezone | string | 否 | GMT+08:00 | 時(shí)區(qū)偏移量,格式為GMT+HH:MM(東區(qū))、GMT-HH:MM(西區(qū))。例如日志時(shí)間為東八區(qū),則該值為GMT+08:00。 |
advanced | JSON object | 否 | 無 | 擴(kuò)展功能。更多信息,請參見advanced參數(shù)說明。 |
sensitive_keys參數(shù)
參數(shù)說明
參數(shù)名稱
數(shù)據(jù)類型
是否必填
示例值
描述
key
string
是
content
日志字段名稱。
type
string
是
const
脫敏方式。可選值如下:
const:將敏感內(nèi)容替換成const字段取值內(nèi)容。
md5:將敏感內(nèi)容替換為其對應(yīng)的MD5值。
regex_begin
string
是
'password':'
敏感內(nèi)容前綴的正則表達(dá)式,用于查找敏感內(nèi)容。使用RE2語法。更多信息,請參見RE2語法。
regex_content
string
是
[^']*
敏感內(nèi)容的正則表達(dá)式,使用RE2語法。更多信息,請參見RE2語法。
all
boolean
是
true
是否替換該字段中所有的敏感內(nèi)容。可選值如下:
true(推薦):替換。
false:只替換字段中匹配正則表達(dá)式的第一部分內(nèi)容。
const
string
否
"********"
當(dāng)type設(shè)置為const時(shí),必須配置。
配置示例
例如日志中content字段的值為
[{'account':'1812213231432969','password':'04a23f38'}, {'account':'1812213685634','password':'123a'}]
,現(xiàn)需要將password
部分替換為********,則設(shè)置sensitive_keys為如下內(nèi)容。sensitive_keys = [{"all": true, "const": "********", "regex_content": "[^']*", "regex_begin": "'password':'", "type": "const", "key": "content"}]
日志樣例
[{'account':'1812213231432969','password':'********'}, {'account':'1812213685634','password':'********'}]
advanced參數(shù)
參數(shù)名稱 | 數(shù)據(jù)類型 | 是否必填 | 示例 | 描述 |
enable_root_path_collection | boolean | 否 | false | 是否允許采集Windows根目錄(例如D:\log*)中的數(shù)據(jù)。
重要
|
exactly_once_concurrency | int | 否 | 1 | 是否啟用ExactlyOnce寫入功能。ExactlyOnce寫入功能用于指定單個(gè)文件允許的發(fā)送并發(fā)數(shù)。取值范圍:0~512。更多信息,請參見附錄:ExactlyOnce寫入功能說明。可選值如下:
重要
|
enable_log_position_meta | boolean | 否 | true | 是否在日志中添加該日志所屬原始文件的元數(shù)據(jù)信息,即新增__tag__:__inode__字段和__file_offset__字段。可選值如下:
說明 僅支持Logtail 1.0.21及以上版本。 |
specified_year | uint | 否 | 0 | 當(dāng)原始日志的時(shí)間缺少年份信息時(shí),您可以設(shè)置該參數(shù),使用當(dāng)前時(shí)間中的年份或指定年份補(bǔ)全日志時(shí)間。可選值如下:
說明 僅支持Logtail 1.0.21及以上版本。 |
force_multiconfig | boolean | 否 | false | 是否允許該Logtail配置采集其他Logtail配置已匹配的文件。默認(rèn)值:false,表示不允許。 適用于文件多寫場景,例如一個(gè)文件通過兩個(gè)采集配置采集到不同的logstore。 |
raw_log_tag | string | 否 | __raw__ | 上傳原始日志時(shí),用于存放原始日志的字段,默認(rèn)值:__raw__。 |
blacklist | object | 否 | 無 | 采集黑名單配置。更多信息,請參見blacklist參數(shù)說明。 |
tail_size_kb | int | 否 | 1024 | 新文件首次采集的大小。通過首次采集大小,可以確認(rèn)首次采集的位置。日志服務(wù)默認(rèn)首次采集大小為1024 KB,即:
您可以通過此處修改首次采集大小,取值范圍:0~10485760,單位:KB。 |
batch_send_interval | int | 否 | 3 | 聚合發(fā)送周期。單位:秒,默認(rèn)值:3。 |
max_rotate_queue_size | int | 否 | 20 | 單文件輪轉(zhuǎn)隊(duì)列的長度。默認(rèn)值:20。 |
enable_precise_timestamp | boolean | 否 | false | 是否提取高精度時(shí)間。如果未添加該參數(shù),則默認(rèn)使用false,表示不提取高精度時(shí)間。 默認(rèn)情況下,設(shè)置為true后,Logtail會(huì)將指定的時(shí)間字段值解析為毫秒級(jí)別的時(shí)間戳,并存入precise_timestamp_key參數(shù)對應(yīng)的字段。更多信息,請參見Logtail日志采集支持高精度時(shí)間戳。 說明
|
precise_timestamp_key | string | 否 | "precise_timestamp" | 保存高精度時(shí)間戳的字段。如果未添加該參數(shù),則默認(rèn)為precise_timestamp字段。 |
precise_timestamp_unit | string | 否 | "ms" | 高精度時(shí)間戳的單位。如果未添加該參數(shù),則默認(rèn)為ms。取值包括ms(毫秒)、us(微秒)、ns(納秒)。 |
其中,blacklist參數(shù)說明如下表所示。
參數(shù)名稱 | 數(shù)據(jù)類型 | 是否必填 | 示例 | 描述 |
dir_blacklist | array | 否 | ["/home/admin/dir1", "/home/admin/dir2*"] | 目錄(絕對路徑)黑名單。支持使用通配符星號(hào)(*)匹配多個(gè)目錄。 例如配置路徑為/home/admin/dir1,則表示在采集時(shí)忽略/home/admin/dir1目錄下的所有內(nèi)容。 |
filename_blacklist | array | 否 | ["app*.log", "password"] | 文件名黑名單,指定的文件名在任何目錄下都不會(huì)被采集。支持使用通配符星號(hào)(*)匹配多個(gè)文件名。 |
filepath_blacklist | array | 否 | ["/home/admin/private*.log"] | 文件路徑(絕對路徑)黑名單。支持使用通配符星號(hào)(*)匹配多個(gè)文件。 配置路徑為/home/admin/private*.log,則表示在采集時(shí)忽略/home/admin/目錄下所有以private開頭,以.log結(jié)尾的文件。 |
文本日志的Logtail特有配置
基礎(chǔ)參數(shù)
參數(shù)名稱 | 數(shù)據(jù)類型 | 是否必填 | 示例 | 描述 |
logType | string | 是 | common_reg_log | 日志的采集模式。具體說明如下:
|
logPath | string | 是 | /var/log/http/ | 日志文件的路徑。 |
filePattern | string | 是 | access*.log | 日志文件名稱。 |
topicFormat | string | 是 | none | Topic生成方式。可選值如下:
更多信息,請參見日志主題。 |
timeFormat | string | 否 | %Y/%m/%d %H:%M:%S | 日志時(shí)間格式。更多信息,請參見時(shí)間格式。 |
preserve | boolean | 否 | true | 如果一個(gè)日志文件在指定時(shí)間內(nèi)沒有任何更新,則認(rèn)為該文件已超時(shí)。可選值如下:
|
preserveDepth | integer | 否 | 1 | 當(dāng)設(shè)置preserve為false時(shí),需指定最大超時(shí)目錄深度,取值范圍:1~3。 |
fileEncoding | string | 否 | utf8 | 日志文件編碼格式,取值為utf8、gbk。 |
discardUnmatch | boolean | 否 | true | 是否丟棄匹配失敗的日志。可選值如下:
|
maxDepth | int | 否 | 100 | 設(shè)置日志目錄被監(jiān)控的最大深度。取值范圍:0~1000,0代表只監(jiān)控本層目錄。 |
delaySkipBytes | int | 否 | 0 | 采集落后時(shí)是否丟棄落后數(shù)據(jù)的閾值。可選值如下:
|
dockerFile | boolean | 否 | false | 采集的目標(biāo)文件是否為容器內(nèi)文件,默認(rèn)為false。 |
dockerIncludeLabel | JSON object | 否 | 無 | 容器Label白名單,用于指定待采集的容器。默認(rèn)為空,表示采集所有容器的日志或標(biāo)準(zhǔn)輸出。如果您要設(shè)置容器Label白名單,那么LabelKey必填,LabelValue可選填。
說明
|
dockerExcludeLabel | JSON object | 否 | 無 | 容器Label黑名單,用于排除不采集的容器。默認(rèn)為空,表示不排除任何容器。如果您要設(shè)置容器Label黑名單,那么LabelKey必填,LabelValue可選填。
說明
|
dockerIncludeEnv | JSON object | 否 | 無 | 環(huán)境變量白名單,用于指定待采集的容器。默認(rèn)為空,表示采集所有容器的日志或標(biāo)準(zhǔn)輸出。如果您要設(shè)置環(huán)境變量白名單,那么EnvKey必填,EnvValue可選填。
說明 多個(gè)白名單之間為或關(guān)系,即只要容器的環(huán)境變量滿足任一白名單即可匹配。 |
dockerExcludeEnv | JSON object | 否 | 無 | 環(huán)境變量黑名單,用于排除不采集的容器。默認(rèn)為空,表示不排除任何容器。如果您要設(shè)置環(huán)境變量黑名單,那么EnvKey必填,EnvValue可選填。
說明 多個(gè)黑名單之間為或關(guān)系,即只要容器的環(huán)境變量滿足任一鍵值對即可被排除。 |
完整正則模式和極簡模式特有配置
參數(shù)說明
參數(shù)名稱
數(shù)據(jù)類型
是否必填
示例值
描述
key
array
是
["content"]
字段列表,用于為原始日志內(nèi)容配置字段。
logBeginRegex
string
否
.*
行首正則表達(dá)式。
regex
string
否
(.*)
提取字段的正則表達(dá)式。
配置示例
{ "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模式特有配置
參數(shù)名稱 | 數(shù)據(jù)類型 | 是否必填 | 示例值 | 描述 |
timeKey | string | 否 | time | 指定時(shí)間字段的key名稱。 |
分隔符模式特有配置
參數(shù)說明
參數(shù)名稱
數(shù)據(jù)類型
是否必填
示例值
描述
separator
string
否
,
根據(jù)您的日志格式選擇正確的分隔符。更多信息,請參見使用分隔符模式采集日志。
quote
string
是
\
當(dāng)日志字段內(nèi)容中包含分隔符時(shí),需要指定引用符進(jìn)行包裹,被引用符包裹的內(nèi)容會(huì)被日志服務(wù)解析為一個(gè)完整字段。請根據(jù)您的日志格式選擇正確的引用符。更多信息,請參見使用分隔符模式采集日志。
key
array
是
[ "ip", "time"]
字段列表,用于為原始日志內(nèi)容配置字段。
timeKey
string
是
time
指定key列表中的某個(gè)字段為時(shí)間字段。
autoExtend
boolean
否
true
如果日志中分割出的字段數(shù)少于配置的Key數(shù)量,是否上傳已解析的字段。
例如日志為11|22|33|44|55,分隔符為豎線(|),日志內(nèi)容將被解析為11、22、33、44和55,為其分別設(shè)置Key為A、B、C、D和E。
true:采集日志11|22|33|55時(shí),55會(huì)作為Key D的Value被上傳到日志服務(wù)。
false:采集日志11|22|33|55時(shí),該條日志會(huì)因字段與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" } }
飛天模式特有配置
參數(shù)名稱 | 數(shù)據(jù)類型 | 是否必填 | 示例值 | 描述 |
logBeginRegex | string | 否 | .* | 行首正則表達(dá)式。 |
Logtail插件的特有配置
參數(shù)說明
插件模式特有的配置說明如下表所示。
參數(shù)名稱
數(shù)據(jù)類型
是否必填
示例值
描述
plugin
JSON object
是
無
使用Logtail插件采集日志時(shí),需配置此參數(shù)。更多信息,請參見使用Logtail插件采集數(shù)據(jù)。
配置示例
{ "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參數(shù)說明
用于配置日志輸出的Project和Logstore。
參數(shù)名稱 | 數(shù)據(jù)類型 | 是否必填 | 示例值 | 描述 |
projectName | string | 是 | my-project | Project名稱,必須為請求的Project名稱。 |
logstoreName | string | 是 | my-logstore | Logstore名稱。 |
附錄:ExactlyOnce寫入功能說明
開啟ExactlyOnce寫入功能后,Logtail會(huì)在本地磁盤記錄細(xì)粒度的Checkpoint信息(文件級(jí)別)。當(dāng)出現(xiàn)進(jìn)程異常、機(jī)器重啟等情況后,Logtail會(huì)在啟動(dòng)時(shí)借助Checkpoint信息來確定每個(gè)文件需要重新處理的范圍以及通過日志服務(wù)端對于重復(fù)數(shù)據(jù)的拒絕機(jī)制(遞增序號(hào)),可有效避免數(shù)據(jù)的重復(fù)發(fā)送。但該功能會(huì)占用一定的磁盤寫入資源。相關(guān)限制如下:
Checkpoint信息需要利用本地磁盤進(jìn)行存儲(chǔ)。如果是磁盤原因?qū)е翪heckpoint無法記錄(磁盤滿)或者內(nèi)容損壞(磁盤故障),可能導(dǎo)致恢復(fù)失敗。
Checkpoint僅記錄文件的元數(shù)據(jù)信息,不包含文件數(shù)據(jù)。所以如果文件本身被刪除或者修改,可能導(dǎo)致無法恢復(fù)。
ExactlyOnce寫入功能依賴日志服務(wù)端記錄的當(dāng)前寫入序號(hào),目前每個(gè)Shard僅支持10,000條記錄,在超出限制后,會(huì)產(chǎn)生記錄替換。因此為了保證可靠性,對于寫入同一個(gè)Logstore的活躍文件數(shù)*Logtail實(shí)例數(shù)的結(jié)果不可超過9500(建議預(yù)留一定量)。
活躍文件數(shù):正在被讀取和發(fā)送的文件數(shù)量。同一個(gè)邏輯文件名的不同輪轉(zhuǎn)文件會(huì)串行發(fā)送,它們僅被算作一個(gè)活躍文件。
Logtail實(shí)例數(shù):即Logtail進(jìn)程數(shù)。默認(rèn)情況下每臺(tái)機(jī)器就一個(gè)實(shí)例,即一般情況下等同于機(jī)器數(shù)。
出于性能考慮,默認(rèn)寫入Checkpoint時(shí)不會(huì)調(diào)用sync落盤,所以如果機(jī)器重啟導(dǎo)致buffer數(shù)據(jù)來不及寫入磁盤時(shí),可能導(dǎo)致Checkpoint丟失。您可以在Logtail啟動(dòng)參數(shù)配置文件(/usr/local/ilogtail/ilogtail_config.json)中,增加"enable_checkpoint_sync_write": true,
,開啟sync寫功能。具體操作,請參見設(shè)置Logtail啟動(dòng)參數(shù)。