All Products
Search

This Product

    Simple Log Service:Logtail and LoongCollector compatibility

    Document Center

    Simple Log Service:Logtail and LoongCollector compatibility

    Last Updated:Mar 01, 2026

    This topic describes the version differences between Logtail and LoongCollector. It also explains how to upgrade from Logtail to LoongCollector and how to roll back from 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 system does not output the last log line that does not end with a carriage return, or the last multi-line segment, until it receives a carriage return or the next multi-line segment.

      • 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. You cannot adjust this 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 host scenarios

    Upgrade from Logtail to LoongCollector

    Run the appropriate command from the following table to upgrade Logtail to LoongCollector based on the host operating system.

    Host type

    Operating system

    Download method

    Installation method

    Linux

    ARM

    The host is connected to the internet. Download the script directly.

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

    You can choose the installation command based on your network conditions.

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

    x86-64

    ARM

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

    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, run the installation command.

    # Install locally
chmod +x loongcollector.sh; ./loongcollector.sh upgrade-local

    x86-64

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

    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;

    The upgrade is successful if the following information is displayed.

    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

    Run the appropriate command from the following table to roll back LoongCollector to Logtail.

    Note

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

    Operating system

    Download method

    Upgrade method

    ARM and x86-64

    Host has Internet access:

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

    After download completes, run the upgrade command.

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

    To specify a particular version, run this command instead.

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

    ARM

    Host is offline. First, download the installation script and package on a server with Internet access:

    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 target server. Then run the upgrade command.

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

    x86-64

    Host is offline. First, download the installation script and package on a server with Internet access:

    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;