All Products
Search
Document Center

Simple Log Service:Logtail configurations (Legacy)

Last Updated:Jun 08, 2026

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:

  • It can contain only lowercase letters, digits, hyphens (-), and underscores (_).

  • It must start and end with a lowercase letter or a digit.

  • It must be 2 to 128 characters in length.

inputType

string

Yes

file

Data source type. Valid values:

  • plugin: Collects logs using Logtail plug-ins (for example, MySQL Binlog).

  • file: Collects logs from text files using a fixed mode (full regex, delimiter, and others).

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.

  • Load balancing (LoadBalance) mode: Writes to any writable shard. Best for scenarios without ordering requirements.

  • Shard (KeyHash) mode: Routes data to a specific shard based on the Key field in URL parameters. Falls back to load balancing if not set. Ensures strict ordering within a shard during merging and splitting. Shards.

When configured, data is written in shard mode. The __source__ field is supported.

enableRawLog

boolean

No

false

Whether to upload raw logs.

  • true: Upload raw logs.

  • false (default): Do not upload raw logs.

sensitive_keys

array

No

None

Data masking configuration. sensitive_keys parameters.

mergeType

string

No

topic

The aggregation method. Valid values:

  • topic (default): Aggregates by topic.

  • logstore: Aggregates by Logstore.

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 the password field 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*).

  • true: Allowed.

  • false (default): Not allowed.

Important
  • Global parameter. Enabling this in any Logtail configuration allows all configurations on the server to collect from root directories until Logtail restarts.

  • This feature is supported only on Windows Logtail 1.0.0.22 and later.

exactly_once_concurrency

int

No

1

Enables ExactlyOnce write and sets the number of concurrent sends per file (0-512). Appendix: ExactlyOnce write feature.

  • 0: Disables the ExactlyOnce write feature.

  • Other values: Enables ExactlyOnce write with the specified concurrency per file.

Important
  • Higher values increase memory and disk overhead. Set based on your local write traffic.

  • Logtail performs local randomization. Even if this value is less than the shard count, write balancing is still ensured.

  • Takes effect only on new files after configuration.

  • This feature is supported only in Logtail 1.0.21 and later.

enable_log_position_meta

boolean

No

true

Whether to add log file metadata (__tag__:__inode__ and __file_offset__ fields).

  • true: Adds the metadata.

  • false: Does not add the metadata.

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:

  • 0: Uses the current year.

  • A specific year (for example, 2020): Uses the specified year.

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.

  • Files smaller than 1024 KB: collection starts from the beginning.

  • Files larger than 1024 KB: collection starts 1024 KB before the end.

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
  • System time must be disabled in the Logtail collection configuration.

  • This feature is supported only in Logtail 1.0.32 and later.

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:

  • json_log: JSON mode.

  • common_reg_log: Full regex mode.

  • plugin: Plug-in mode.

  • delimiter_log: Delimiter mode.

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:

  • none: Does not generate log topics.

  • default: Uses the log file path as the log topic.

  • group_topic: Uses the machine group topic as the log topic.

  • File path regex: Uses part of the log file path as the topic. Example: /var/log/(.*).log.

Log topics.

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:

  • true (default): Never times out.

  • false: Times out after 30 minutes of inactivity. The file is no longer monitored.

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:

  • true: Discards logs that fail to be matched.

  • false: Does not discard logs that fail to be matched.

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:

  • 0 (default): Does not discard data.

  • Other values: If the collection delay exceeds this value (for example, 1024 KB), the delayed data is discarded.

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.

  • If LabelValue is empty, all containers with a label that includes the LabelKey are matched.

  • If LabelValue is not empty, only containers with a label of LabelKey=LabelValue are matched.

    By default, LabelValue is matched as a string. A match occurs only if the LabelValue is identical to the container label's value. If the value starts with ^ and ends with $, it is treated as a regular expression. For example, set LabelKey to io.kubernetes.container.name and LabelValue to ^(nginx|cube)$ to match containers named nginx or cube.

Note
  • Do not set the same LabelKey multiple times. If there are duplicates, only one will take effect.

  • Multiple whitelist entries have an OR relationship. A container is matched if its label satisfies any of the whitelist entries.

dockerExcludeLabel

JSON object

No

None

Container label blacklist. Empty by default (no containers excluded). LabelKey is required; LabelValue is optional.

  • If LabelValue is empty, all containers with a label that includes the LabelKey are excluded.

  • If LabelValue is not empty, only containers with a label of LabelKey=LabelValue are excluded.

    By default, LabelValue is matched as a string. A match occurs only if the LabelValue is identical to the container label's value. If the value starts with ^ and ends with $, it is treated as a regular expression. For example, set LabelKey to io.kubernetes.container.name and LabelValue to ^(nginx|cube)$ to match containers named nginx or cube.

Note
  • Do not set the same LabelKey multiple times. If there are duplicates, only one will take effect.

  • Multiple blacklist entries have an OR relationship. A container is excluded if its label satisfies any of the blacklist key-value pairs.

dockerIncludeEnv

JSON object

No

None

Environment variable whitelist. Empty by default (collects from all containers). EnvKey is required; EnvValue is optional.

  • If EnvValue is empty, all containers with an environment variable that includes the EnvKey are matched.

  • If EnvValue is not empty, only containers with an environment variable of EnvKey=EnvValue are matched.

    By default, EnvValue is matched as a string. A match occurs only if the EnvValue is identical to the environment variable's value. If the value starts with ^ and ends with $, it is treated as a regular expression. For example, set EnvKey to NGINX_SERVICE_PORT and EnvValue to ^(80|6379)$ to match containers with a service port of 80 or 6379.

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.

  • If EnvValue is empty, all containers with an environment variable that includes the EnvKey are excluded.

  • If EnvValue is not empty, only containers with an environment variable of EnvKey=EnvValue are excluded.

    By default, EnvValue is matched as a string. A match occurs only if the EnvValue is identical to the environment variable's value. If the value starts with ^ and ends with $, it is treated as a regular expression. For example, set EnvKey to NGINX_SERVICE_PORT and EnvValue to ^(80|6379)$ to match containers with a service port of 80 or 6379.

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.