All Products
Search

This Product

    Simple Log Service:Logtail and LoongCollector compatibility

    Document Center

    Simple Log Service:Logtail and LoongCollector compatibility

    Last Updated:Jan 16, 2026

    This topic describes the version history and core feature changes of the Logtail and LoongCollector log collection tools. It also describes how to upgrade Logtail to LoongCollector and how to roll back LoongCollector to Logtail.

    Version comparison

    Version naming changes

    Logtail, iLogtail, and LoongCollector are different names for the same software at different stages:

    • Logtail/iLogtail: The name used for versions before 3.0.

    • LoongCollector: The name used for versions 3.0 and later.

    Standardization of log and tag parsing

    1. Handling duplicate keys in the log entity:

      • After version 1.8: Duplicate keys are not allowed in the log entity. For example, if the input is content: xxx, content: yyy, only content: xxx is retained.

      • Before version 1.8: All duplicate keys are retained and renamed. For example, the output is content: xxx, content_0: yyy.

    2. Handling duplicate keys in log tags:

      • After version 1.8: Duplicate keys are not allowed in log tags. For example, if the input is __tag__:tag: xxx, __tag__:tag: yyy, only __tag__:tag: xxx is retained.

      • Before version 1.8: All duplicate keys are retained and renamed. For example, the output is __tag__:tag: xxx, __tag__:tag_0: yyy.

    Enhancements for single-line and multi-line log processing

    1. Changes in exception handling:

      • Version 2.x: By default, logs are split by \n. To discard unmatched content, set the Multiline.UnmatchedContentTreatment parameter to discard.

      • Version 1.x: If a log cannot be matched to a multi-line start pattern, the entire content is processed as a single log.

    2. Processing of the last log line:

      • Before version 1.8: The last log line that does not end with a carriage return, or the last multi-line segment, is not output until a carriage return or the next multi-line segment is received.

      • After version 1.8: A timeout mechanism is introduced to control this behavior. To ensure the integrity of the last segment, the default delay is 60 seconds. This cannot be adjusted before version 2.0. Starting from version 2.0, the global control parameter is default_reader_flush_timeout, and the collection configuration-level control parameter is FlushTimeoutSecs. If your application is sensitive to delays, you can adjust these parameters. Do not set these parameters to 0, because this may cause log truncation.

    Changes in the tag processing mechanism

    Tags processed by an extension are written to the tags structure of the data model instead of the content structure. This method significantly saves space:

    • This affects data consumption scenarios and requires you to handle compatibility.

    • This does not affect query scenarios.

    Changes in the container log collection path

    When you collect container logs from an ACK cluster, if you create the configuration using the ACK console:

    • From version 2.0 onwards: The default maximum recursion depth for a folder is 0. If the collection path contains /**/, the depth is 10.

    • Before version 2.0: The default maximum recursion depth is 100.

    Upgrade Logtail to LoongCollector in server scenarios

    Upgrade from Logtail to LoongCollector

    To upgrade Logtail to LoongCollector, find the appropriate command for your server in the table below and run it.

    Host type

    Operating system

    Download method

    Installation method

    Linux

    ARM

    The server has an Internet connection and can download directly.

    wget https://aliyun-observability-release-${region_id}.oss-${region_id}.aliyuncs.com/loongcollector/linux64/latest/loongcollector.sh -O loongcollector.sh;

    Select the installation command based on your network connection.

    # Install from the Internet
chmod +x loongcollector.sh; ./loongcollector.sh upgrade

    x86-64

    ARM

    The server is offline. First, download the installation script and package on a server that can access the Internet.

    wget https://aliyun-observability-release-${region_id}.oss-${region_id}.aliyuncs.com/loongcollector/linux64/latest/loongcollector.sh;wget http://aliyun-observability-release-${region_id}.oss-${region_id}.aliyuncs.com/loongcollector/linux64/latest/aarch64/main/loongcollector-linux64.tar.gz;

    Copy the installation script and package to the server where you want to install LoongCollector. Then, select the installation command based on your network connection.

    # Install from the Internet
chmod +x loongcollector.sh; ./loongcollector.sh upgrade-local

    x86-64

    The server is offline. First, download the installation script and package on a server that can access the Internet.

    wget https://aliyun-observability-release-${region_id}.oss-${region_id}.aliyuncs.com/loongcollector/linux64/latest/loongcollector.sh;wget http://aliyun-observability-release-${region_id}.oss-${region_id}.aliyuncs.com/loongcollector/linux64/latest/x86_64/main/loongcollector-linux64.tar.gz;

    If the following information is displayed, the upgrade is successful.

    Try to stop ilogtail ...
kill process Name: ilogtail pid: 878
kill process Name: ilogtail pid: 879
stop successfully
Stop ilogtail successfully.
Upgrading loongcollector files ...
Upgrade loongcollector files successfully.
Starting loongcollector ...
loongcollector is running
Upgrade loongcollector successfully.

    Roll back from LoongCollector to Logtail

    To roll LoongCollector back to Logtail, find the appropriate command for your server in the table below and run it.

    Note

    You must download the logtail.sh script again. Do not use the old logtail.sh script.

    Operating system

    Download method

    Upgrade methods

    ARM and x86-64

    The server has an Internet connection:

    wget https://logtail-release-${region_id}.oss-${region_id}.aliyuncs.com/linux64/logtail.sh -O logtail.sh; 

    After the download is complete, run the upgrade command.

    chmod +x logtail.sh; sudo ./logtail.sh upgrade;

    To specify a version, run the following command.

    # For example, to specify version 1.8.7, replace the version number as needed.
chmod +x logtail.sh; sudo ./logtail.sh upgrade -v -v 1.8.7;

    ARM

    The server is offline. First, download the installation script and package on a server that can access the Internet:

    wget https://logtail-release-${region_id}.oss-${region_id}.aliyuncs.com/linux64/logtail.sh; wget http://logtail-release-${region_id}.oss-${region_id}.aliyuncs.com/linux64/aarch64/logtail-linux64.tar.gz;

    Copy the installation script and package to the server where you want to upgrade Logtail. Then, run the following upgrade command.

    chmod +x logtail.sh; ./logtail.sh upgrade-local;

    x86-64

    The server is offline. First, download the installation script and package on a server that can access the Internet:

    wget https://logtail-release-${region_id}.oss-${region_id}.aliyuncs.com/linux64/logtail.sh; wget http://logtail-release-${region_id}.oss-${region_id}.aliyuncs.com/linux64/logtail-linux64.tar.gz;