A Logtail configuration defines log collection policies such as data source and collection mode. This topic describes the legacy API parameters.
The legacy CRD-AliyunLogConfig is no longer maintained. Use AliyunPipelineConfig instead. CreateLogtailPipelineConfig - Create a Logtail pipeline configuration.
Basic parameters
|
Parameter |
Type |
Required |
Example |
Description |
|
configName |
string |
Yes |
config-sample |
Logtail configuration name. Must be unique within the project and immutable after creation. Naming rules:
|
|
inputType |
string |
Yes |
file |
Data source type. Valid values:
|
|
inputDetail |
JSON object |
Yes |
None |
Data source configuration. inputDetail parameters. |
|
outputType |
string |
Yes |
LogService |
Output destination. Only LogService is supported. |
|
outputDetail |
JSON object |
Yes |
None |
Log output configuration. outputDetail parameters. |
|
logSample |
string |
No |
None |
The sample log. Note
The sample log must be less than 1,500 bytes in length. |
inputDetail parameters
Basic parameters
|
Parameter |
Type |
Required |
Example |
Description |
|
filterKey |
array |
No |
["ip"] |
Log filter fields. Only logs matching the filterRegex patterns are collected. Note
This parameter is for text log collection only. |
|
filterRegex |
array |
No |
["^10.*"] |
Regex patterns for filterKey. The filterRegex array length must match filterKey. Note
This parameter is for text log collection only. |
|
shardHashKey |
array |
No |
["__source__"] |
Data write mode. Default: load balancing.
When configured, data is written in shard mode. The __source__ field is supported. |
|
enableRawLog |
boolean |
No |
false |
Whether to upload raw logs.
|
|
sensitive_keys |
array |
No |
None |
Data masking configuration. sensitive_keys parameters. |
|
mergeType |
string |
No |
topic |
The aggregation method. Valid values:
|
|
delayAlarmBytes |
int |
No |
209715200 |
Alert threshold for collection delay. Default: 209715200 (200 MB). |
|
adjustTimezone |
boolean |
No |
false |
Whether to adjust log time zones. Applies only when time parsing is configured (e.g., when timeFormat is set). |
|
logTimezone |
string |
No |
GMT+08:00 |
Time zone offset. Format: GMT+HH:MM (east) or GMT-HH:MM (west). Example: GMT+08:00 for UTC+8. |
|
advanced |
JSON object |
No |
None |
Advanced feature configuration. advanced parameters. |
sensitive_keys parameters
-
Parameters
Parameter
Type
Required
Example
Description
key
string
Yes
content
The name of the log field.
type
string
Yes
const
The data masking method. Valid values:
-
const: Replaces sensitive content with the value of the const field.
-
md5: Replaces sensitive content with its corresponding MD5 hash.
regex_begin
string
Yes
'password':'
Regex prefix for locating sensitive content. Uses RE2 syntax.
regex_content
string
Yes
[^']*
Regex for the sensitive content. Uses RE2 syntax.
all
boolean
Yes
true
Whether to replace all sensitive content in the field.
-
true (recommended): Replaces all sensitive content.
-
false: Replaces only the first match.
const
string
No
"********"
This parameter is required if you set type to const.
-
-
Configuration example
For example, if the value of the content field in a log is
[{'account':'1812213231432969','password':'04a23f38'}, {'account':'1812213685634','password':'123a'}], you can replace the value of thepasswordfield with ******** by setting sensitive_keys as follows.sensitive_keys = [{"all": true, "const": "********", "regex_content": "[^']*", "regex_begin": "'password':'", "type": "const", "key": "content"}] -
Sample log
[{'account':'1812213231432969','password':'********'}, {'account':'1812213685634','password':'********'}]
Advanced parameters
|
Parameter |
Type |
Required |
Example |
Description |
|
enable_root_path_collection |
boolean |
No |
false |
Whether to allow collection from Windows root directories (for example, D:\log*).
Important
|
|
exactly_once_concurrency |
int |
No |
1 |
Enables ExactlyOnce write and sets the number of concurrent sends per file (0-512). Appendix: ExactlyOnce write feature.
Important
|
|
enable_log_position_meta |
boolean |
No |
true |
Whether to add log file metadata (__tag__:__inode__ and __file_offset__ fields).
Note
This feature is supported only in Logtail 1.0.21 and later. |
|
specified_year |
uint |
No |
0 |
Completes log timestamps that are missing the year. Valid values:
Note
This feature is supported only in Logtail 1.0.21 and later. |
|
force_multiconfig |
boolean |
No |
false |
Whether to allow this configuration to collect files already matched by other configurations. Default: false. Use for multi-write scenarios where a file is collected by two configurations into different Logstores. |
|
raw_log_tag |
string |
No |
__raw__ |
Field name for storing raw logs. Default: __raw__. |
|
blacklist |
object |
No |
None |
Collection blacklist configuration. blacklist parameters. |
|
tail_size_kb |
int |
No |
1024 |
Initial collection size for new files, determining the starting read position. Default: 1024 KB.
Range: 0-10485760 KB. |
|
batch_send_interval |
int |
No |
3 |
Aggregation send interval in seconds. Default: 3. |
|
max_rotate_queue_size |
int |
No |
20 |
Single-file rotation queue length. Default: 20. |
|
enable_precise_timestamp |
boolean |
No |
false |
Whether to extract high-precision time. Default: false. When enabled, Logtail parses the time field into a millisecond-level timestamp and stores it in the precise_timestamp_key field. Note
|
|
precise_timestamp_key |
string |
No |
"precise_timestamp" |
Field for storing the high-precision timestamp. Default: precise_timestamp. |
|
precise_timestamp_unit |
string |
No |
"ms" |
Unit of the high-precision timestamp. Default: ms. Valid values: ms (millisecond), us (microsecond), ns (nanosecond). |
The following table describes the parameters of blacklist.
|
Parameter |
Type |
Required |
Example |
Description |
|
dir_blacklist |
array |
No |
["/home/admin/dir1", "/home/admin/dir2*"] |
Directory blacklist (absolute paths). Supports asterisk (*) wildcards. For example, if you configure the path as /home/admin/dir1, all content in the /home/admin/dir1 directory is ignored during collection. |
|
filename_blacklist |
array |
No |
["app*.log", "password"] |
File name blacklist. Matched files are excluded from all directories. Supports asterisk (*) wildcards. |
|
filepath_blacklist |
array |
No |
["/home/admin/private*.log"] |
File path blacklist (absolute paths). Supports asterisk (*) wildcards. If you configure the path as /home/admin/private*.log, all files in the /home/admin/ directory that start with "private" and end with ".log" are ignored during collection. |
Configurations specific to text logs
Basic parameters
|
Parameter |
Type |
Required |
Example |
Description |
|
logType |
string |
Yes |
common_reg_log |
Log collection mode. Valid values:
|
|
logPath |
string |
Yes |
/var/log/http/ |
Log file directory path. |
|
filePattern |
string |
Yes |
access*.log |
Log file name pattern. |
|
topicFormat |
string |
Yes |
none |
The topic generation method. Valid values:
|
|
timeFormat |
string |
No |
%Y/%m/%d %H:%M:%S |
The log time format. Time formats. |
|
preserve |
boolean |
No |
true |
Log file timeout behavior. Valid values:
|
|
preserveDepth |
integer |
No |
1 |
Maximum directory depth for timeout when preserve is false. Range: 1-3. |
|
fileEncoding |
string |
No |
utf8 |
Log file encoding. Valid values: utf8, gbk. |
|
discardUnmatch |
boolean |
No |
true |
Whether to discard logs that fail to be matched. Valid values:
|
|
maxDepth |
int |
No |
100 |
Maximum depth of the monitored log directory (0-1,000). A value of 0 monitors only the current directory. |
|
delaySkipBytes |
int |
No |
0 |
The threshold for discarding delayed data. Valid values:
|
|
dockerFile |
boolean |
No |
false |
Whether the target file is inside a container. Default: false. |
|
dockerIncludeLabel |
JSON object |
No |
None |
Container label whitelist. Empty by default (collects from all containers). LabelKey is required; LabelValue is optional.
Note
|
|
dockerExcludeLabel |
JSON object |
No |
None |
Container label blacklist. Empty by default (no containers excluded). LabelKey is required; LabelValue is optional.
Note
|
|
dockerIncludeEnv |
JSON object |
No |
None |
Environment variable whitelist. Empty by default (collects from all containers). EnvKey is required; EnvValue is optional.
Note
Multiple whitelist entries have an OR relationship. A container is matched if its environment variables satisfy any of the whitelist entries. |
|
dockerExcludeEnv |
JSON object |
No |
None |
Environment variable blacklist. Empty by default (no containers excluded). EnvKey is required; EnvValue is optional.
Note
Multiple blacklist entries have an OR relationship. A container is excluded if its environment variables satisfy any of the key-value pairs. |
Full regex and simple mode parameters
-
Parameters
Parameter
Type
Required
Example
Description
key
array
Yes
["content"]
Field names for the raw log content.
logBeginRegex
string
No
.*
Regex for the start of a log entry.
regex
string
No
(.*)
Regex for field extraction.
-
Configuration example
{ "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 mode parameters
|
Parameter |
Type |
Required |
Example |
Description |
|
timeKey |
string |
No |
time |
Key name of the time field. |
Delimiter mode parameters
-
Parameters
Parameter
Type
Required
Example
Description
separator
string
No
,
Choose the separator matching your log format. Collect logs in delimiter mode.
quote
string
Yes
\
Quote character for wrapping fields that contain the separator. Enclosed content is parsed as one field. Collect logs in delimiter mode.
key
array
Yes
[ "ip", "time"]
Field names for the raw log content.
timeKey
string
Yes
time
Field from the key list to use as the time field.
autoExtend
boolean
No
true
Whether to upload when split fields are fewer than configured keys.
For example, a log is 11|22|33|44|55, the separator is a vertical bar (|), and the log content is parsed into 11, 22, 33, 44, and 55. The keys are set to A, B, C, D, and E respectively.
-
true: When collecting the log 11|22|33|55, 55 is uploaded to Simple Log Service as the value for key D.
-
false: When collecting the log 11|22|33|55, this log entry is discarded because the number of fields does not match the number of keys.
-
-
Configuration example
{ "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" } }
Plug-in mode parameters
-
Parameters
Parameters for Logtail plug-in log collection.
Parameter
Type
Required
Example
Description
plugin
JSON object
Yes
None
Required for plug-in-based log collection. Use Logtail plug-ins to collect data.
-
Configuration example
{ "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 parameters
Destination project and Logstore parameters.
|
Parameter |
Type |
Required |
Example |
Description |
|
projectName |
string |
Yes |
my-project |
Project name. Must match the project in the request. |
|
logstoreName |
string |
Yes |
my-logstore |
Logstore name. |
Appendix: ExactlyOnce write feature
When enabled, Logtail records file-level checkpoints to disk and uses SLS incremental sequence numbers to prevent duplicate writes. After process errors or restarts, checkpoints determine the reprocessing scope per file. This increases disk write overhead. Limits:
-
Checkpoints are stored on local disk. If disk is full or corrupted, recovery may fail.
-
Checkpoints record file metadata only. If the file is deleted or modified, recovery may not be possible.
-
ExactlyOnce depends on write sequence numbers in SLS. Each shard supports a maximum of 10,000 records. If exceeded, older records are replaced. To ensure reliability, keep `Number of active files × Number of Logtail instances` per Logstore under 9,500.
-
Active files: Files being read and sent. Rotated files with the same logical name count as one active file.
-
Logtail instances: Number of Logtail processes. Typically one per server.
-
Logtail does not call `sync` for checkpoint writes by default. If the server restarts before buffered data reaches disk, checkpoints may be lost. To enable synchronous writes, add "enable_checkpoint_sync_write": true, to the Logtail startup configuration file (/usr/local/ilogtail/ilogtail_config.json). Set Logtail startup parameters.