Log Service limits the collection performance of Logtail. This way, Logtail does not consume an excessive number of server resources and affect other services. If you want to improve the collection performance of Logtail, modify the startup parameters of Logtail.

Scenarios

You can modify the startup parameters of Logtail in the following scenarios:
  • You need to collect a large number of log files and the log files occupy a large amount of memory. For example, you need to collect more than 100 files or monitor more than 5,000 files in specific directories at the same time.
  • Log data is transmitted at a high speed, which causes high CPU utilization. For example, Logtail collects log data at a speed higher than 2 MB/s in simple mode and at a speed higher than 1 MB/s in full regex mode.
  • Logtail sends data to Log Service at a speed higher than 20 MB/s.

Set the startup parameters of Logtail

  1. On the server on which Logtail is installed, open the /usr/local/ilogtail/ilogtail_config.json file.
  2. Set the startup parameters of Logtail based on your business requirements.

    The following example shows how to configure startup parameters:

    {
        ...
        "cpu_usage_limit" : 0.4,
        "mem_usage_limit" : 384,
        "max_bytes_per_sec" : 20971520,
        "process_thread_count" : 1,
        "send_request_concurrency" : 4,
        "buffer_file_num" : 25,
        "buffer_file_size" : 20971520,
        "buffer_file_path" : "",
        ...
    }
    Notice
    • The following table describes the commonly used startup parameters of Logtail. You can use the default values for other startup parameters.
    • You can add and modify specific startup parameters based on your business requirements.

    The following table describes the startup parameters of Logtail.

    Table 1. Startup parameters of Logtail
    Parameter Type Description Example
    cpu_usage_limit double The CPU utilization threshold for Logtail. The threshold is specified based on a single-core CPU.
    • Valid values: 0.1 to the number of CPU cores of the current server.
    • Default value: 2.
    Warning cpu_usage_limit specifies a soft limit. The actual CPU utilization of Logtail may exceed the limit. If the CPU utilization of Logtail remains higher than this limit for 5 minutes, the system triggers a circuit breaker. Then, Logtail automatically restarts.

    For example, if you set the parameter to 0.4, Logtail automatically restarts if the CPU utilization remains higher than 40% for 5 minutes.

    In most cases, a single core can collect logs at a speed of 100 MB/s in simple mode and 20 MB/s in full regex mode.

    "cpu_usage_limit" : 0.4
    mem_usage_limit int The memory usage threshold for Logtail. Unit: MB.
    • Valid values: 128 to 2048.
    • Default value: 2048.
    Warning mem_usage_limit specifies a soft limit. The actual memory usage of Logtail may exceed the limit. If the memory usage of Logtail remains higher than this limit for 5 minutes, the system triggers a circuit breaker. Then, Logtail automatically restarts.
    The following items describe how the setting of the mem_usage_limit parameter affects the number of files that can be monitored:
    • If you use the default value of the mem_usage_limit parameter, each Logtail configuration on each server can be used to monitor up to 19,200 files. Each Logtail client on each server can monitor up to 192,000 files.
    • If you set the mem_usage_limit parameter to the maximum value, each Logtail configuration on each server can be used to monitor up to 100,000 files. Each Logtail client on each server can monitor up to 1,000,000 files.
    The maximum number of files that can be monitored is calculated by using the following formulas:
    • Maximum number of files that can be monitored by using each Logtail configuration = mem_usage_limit/100 × 5,000
    • Maximum number of files that can be monitored by each Logtail client =mem_usage_limit/100 × 50,000
    "mem_usage_limit" : 384
    max_bytes_per_sec int The maximum speed at which Logtail sends raw data. Unit: bytes per second.
    • Valid values: 1024 to 52428800.
    • Default value: 20971520.

    For example, if you set the parameter to 2097152, the speed is limited to 2 MB/s.

    Notice If you set the parameter to a value that is greater than 20971520, the speed is not limited. The value 20971520 indicates that the speed is 20 MB/s.
    "max_bytes_per_sec" : 2097152
    process_thread_count int The number of threads that are used by Logtail to process data.
    • Valid values: 1 to 64.
    • Default value: 1.

    In most cases, a thread provides a write speed of 24 MB/s in simple mode and 12 MB/s in full regex mode. We recommend that you use the default value of this parameter.

    "process_thread_count" : 1
    send_request_concurrency int The number of concurrent requests that are sent by Logtail to asynchronously send data.
    • Valid values: 1 to 1000.
    • Default value: 20.

    If write transactions per second (TPS) is high, you can set this parameter to a value that meets your business requirements. Each concurrent request supports a network throughput of 0.5 MB/s to 1 MB/s. The number of concurrent requests varies based on the network latency.

    Note If the value of this parameter is high, concurrent requests may occupy an excessive number of network ports, and you must adjust the TCP parameters.
    "send_request_concurrency" : 4
    buffer_file_num int The maximum number of cached files.
    • Valid values: 1 to 100.
    • Default value: 25.

    If a network error occurs or the written data exceeds the threshold that you specify, Logtail caches parsed logs to the local files in the installation directory. After the network is recovered and data is written within the threshold, Logtail retries to send the cached logs.

    "buffer_file_num" : 25
    buffer_file_size int The maximum size of a cached file. Unit: bytes.
    • Valid values: 1048576 to 104857600.
    • Default value: 20971520.

    The maximum disk space that can be occupied by cached files is calculated by multiplying the value of the buffer_file_size parameter by the value of the buffer_file_num parameter.

    "buffer_file_size" : 20971520
    buffer_file_path String The directory in which cached files are stored. Default value: null. This value indicates that cached files are stored in the /usr/local/ilogtail directory in which Logtail is installed.

    If you modify this parameter, you must move the cached files whose names match logtail\_buffer\_file_* to the directory that is specified by the new value of the parameter. This way, Logtail can read, send, and delete the cached files.

    "buffer_file_path" : ""
    bind_interface String The name of the Network Interface Card (NIC) that is associated with the server. Default value: null. This value indicates that an available NIC is automatically associated with the server.

    If you set this parameter to eth1, Logtail uses the NIC named eth1 to upload logs.

    This parameter is available only if Logtail runs on the Linux operating system.

    "bind_interface" : ""
    check_point_filename String The path in which the checkpoint file of Logtail is stored. Default value: /tmp/logtail_check_point.

    We recommend that you modify the path and mount the path on the host as a Docker user. If you perform the operations as another type of user, Logtail collects duplicate files when a Docker container is released due to the loss of checkpoint information. For example, you can set the check_point_filename parameter in the Docker container to /data/logtail/check_point.dat, and then add -v /data/docker1/logtail:/data/logtail to the startup command. This way, the /data/docker1/logtail directory of the host is mounted on the /data/logtail directory of the Docker container.

    "check_point_filename" : /tmp/logtail_check_point
    check_point_dump_interval int The interval at which Logtail updates checkpoint files. Default value: 900. Unit: seconds. By default, Logtail updates checkpoint files every 15 minutes.

    This parameter is available only for Logtail V1.0.19 or later.

    "check_point_dump_interval" : 900
    user_config_file_path String The path of the Logtail configuration. By default, Logtail configurations are stored in the directory in which the binary process is stored, and the file name is user_log_config.json.

    We recommend that you modify the path and mount the path on the host as a Docker user. Otherwise, Logtail collects duplicate files when a Docker container is released due to the loss of checkpoint information. For example, you can set the user_config_file_path parameter to /data/logtail/user_log_config.json in the Docker container, and then add -v /data/docker1/logtail:/data/logtail to the startup command. This way, the /data/docker1/logtail directory of the host is mounted on the /data/logtail directory of the Docker container.

    "user_config_file_path" : user_log_config.json
    docker_file_cache_path String The path of the file that records the mappings between the paths of container files and the paths of host files. By default, the file path is /usr/local/ilogtail/docker_path_config.json.

    We recommend that you modify the path and mount the path on the host as a Docker user. Otherwise, Logtail collects duplicate files when a Docker container is released due to the loss of mapping information. For example, you can set the check_point_filename parameter in the Docker container to /data/logtail/check_point.dat, and then add -v /data/docker1/logtail:/data/logtail to the startup command. This way, the /data/docker1/logtail directory of the host is mounted on the /data/logtail directory of the Docker container.

    This parameter is available only for Logtail V0.16.26 or later.

    "docker_file_cache_path": /usr/local/ilogtail/docker_path_config.json
    discard_old_data Boolean Specifies whether to drop historical logs. Default value: true. This value indicates that the logs that were generated 12 hours or more before the current time are dropped. "discard_old_data" : true
    working_ip String The server IP address that is reported by Logtail to Log Service. Default value: null. This value indicates that Log Service automatically obtains the server IP address. "working_ip" : ""
    working_hostname String The server hostname that is reported by Logtail to Log Service. Default value: null. This value indicates that Log Service automatically obtains the server hostname. "working_hostname" : ""
    max_read_buffer_size long The maximum size of each log. Default value: 524288. Unit: bytes.

    If the size of a log exceeds 524288 bytes (512 KB), you can change the value of this parameter.

    "max_read_buffer_size" : 524288
    oas_connect_timeout long The timeout period of the connection that is established by Logtail to send a request to obtain the Logtail configuration or AccessKey pair. Default value: 5. Unit: seconds.

    If the network is unstable or the connection fails to be established, you can change the value of this parameter.

    "oas_connect_timeout" : 5
    oas_request_timeout long The timeout period of the request that is sent by Logtail to obtain the Logtail configuration or AccessKey pair. Default value: 10. Unit: seconds.

    If the network is unstable or the connection fails to be established, you can change the value of this parameter.

    "" : 10
    data_server_port long If you set the data_server_port parameter to 443, Logtail transfers data to Log Service over the HTTPS protocol.

    This parameter is available only for Logtail V1.0.10 or later.

    "data_server_port": 443
    enable_log_time_auto_adjust Boolean If you set the enable_log_time_auto_adjust parameter to true, the log time is automatically changed to the local time of the server.

    To ensure data security, Log Service checks the time information in requests, such as the requests sent by Logtail. Log Service rejects requests that are sent 15 minutes earlier or later than the time in Log Service. The time at which Logtail sends a request is considered as the local time of the server. In some test scenarios, the local time must be set to a future point in time. If you change the local time of the server, Log Service rejects the request and Logtail fails to write data to Log Service. You can use this parameter to synchronize the log time to the local time of the server.

    This parameter is available only for Logtail V1.0.19 or later.

    Notice
    • If you enable the adaptive feature, the offset between the time in Log Service and the local time of the server are added to the log time. The offset is updated only if a request is rejected by Log Service. Therefore, the log time that is queried by Log Service may be different from the time when the log is written.
    • Part of the logic of Logtail changes based on the increment of the system time. We recommend that you restart Logtail after you change the local time of the server.
    "enable_log_time_auto_adjust": true
    accept_multi_config Boolean Specifies whether to allow multiple Logtail clients to collect data from the same file. Default value: false. This value indicates that only one Logtail client can collect the data of a file.

    By default, only one Logtail client can collect the data of a file. You can set this parameter to true to allow multiple clients to collect data from the same file. Each Logtail client has an independent collection process. If multiple Logtail clients are allowed to collect data from the same file, the CPU utilization and memory usage increase.

    This parameter is available only for Logtail V0.16.26 or later.

    "accept_multi_config": true
    enable_checkpoint_sync_write Boolean Specifies whether to enable the sync write feature. Default value: false. This value indicates that the sync write feature is disabled.

    The sync write feature is used together with the ExactlyOnce write feature. If you enable the ExactlyOnce write feature, Logtail records fine-grained checkpoint information by file on your local disk. By default, the sync function is not called when Logtail writes checkpoints to Log Service. If the machine restarts, the data in the buffer cannot be written to the disk and the checkpoints may be lost. In this case, you must set the enable_checkpoint_sync_write parameter to true to enable the sync write feature. For more information, see Appendix: ExactlyOnce write feature.

    This parameter is available only for Logtail V1.0.20 or later.

    "enable_checkpoint_sync_write": false
  3. Restart Logtail for the modified configurations to take effect.
    /etc/init.d/ilogtaild stop && /etc/init.d/ilogtaild start                        

    After you restart Logtail, you can run the /etc/init.d/ilogtaild status command to check the status of Logtail.

Appendix: environment variables

The following table describes the relationships between environment variables and the startup parameters of Logtail. For information about the startup parameters of Logtail, see Table 1.

Table 2. Relationships between environment variables and the startup parameters of Logtail
Parameter Environment variable Priority Supported versions
cpu_usage_limit cpu_usage_limit If you use environment variables and configuration files to modify the startup parameters of Logtail, the modifications from the environment variables take effect. Logtail V0.16.32 or later
mem_usage_limit mem_usage_limit
max_bytes_per_sec max_bytes_per_sec
process_thread_count process_thread_count
send_request_concurrency send_request_concurrency
check_point_filename ALIYUN_LOGTAIL_CHECK_POINT_PATH If you use environment variables and configuration files to modify the startup parameters of Logtail, the modifications from the environment variables take effect. Logtail V0.16.36 or later
docker_file_cache_path docker_file_cache_path If you use environment variables and configuration files to modify the startup parameters of Logtail, the modifications from the configuration files take effect. Logtail 0.16.54 or later
user_config_file_path user_config_file_path If you use environment variables and configuration files to modify the startup parameters of Logtail, the modifications from the configuration files take effect. Logtail V0.16.56 or later
discard_old_data discard_old_data
working_ip ALIYUN_LOGTAIL_WORKING_IP
working_hostname ALIYUN_LOGTAIL_WORKING_HOSTNAME
max_read_buffer_size max_read_buffer_size
oas_connect_timeout oas_connect_timeout
oas_request_timeout oas_request_timeout
data_server_port data_server_port
accept_multi_config accept_multi_config
enable_log_time_auto_adjust enable_log_time_auto_adjust If you use environment variables and configuration files to modify the startup parameters of Logtail, the modifications from the configuration files take effect. Logtail V1.0.19 or later
check_point_dump_interval check_point_dump_interval If you use environment variables and configuration files to modify the startup parameters of Logtail, the modifications from the configuration files take effect. Logtail V1.0.19 or later
enable_checkpoint_sync_write enable_checkpoint_sync_write If you use environment variables and configuration files to modify the startup parameters of Logtail, the modifications from the configuration files take effect. Logtail V1.0.20 or later