All Products
Search

This Product

    Simple Log Service:Logtail and LoongCollector compatibility

    Document Center

    Simple Log Service:Logtail and LoongCollector compatibility

    Last Updated:Mar 12, 2026

    Logtail and LoongCollector refer to the same log collection software at different stages. This document covers behavioral changes across versions and provides upgrade and rollback procedures.

    Behavioral changes across versions

    Version naming

    Logtail, iLogtail, and LoongCollector refer to the same software:

    • Logtail/iLogtail: Versions earlier than 3.0.

    • LoongCollector: Version 3.0 and later.

    Log and tag parsing standardization

    1. Duplicate keys in the log entity:

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

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

    2. Duplicate keys in log tags:

      • Versions 1.8 and later: 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.

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

    Single-line and multi-line log processing

    1. 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. Last log line processing:

      • Versions earlier than 1.8: The system does not output the last log line that does not end with a newline, or the last multi-line segment, until it receives a newline or the next multi-line segment.

      • Versions 1.8 and later: A timeout mechanism controls this behavior. To ensure the integrity of the last segment, the default delay is 60 seconds. Starting from version 2.0, the global control parameter is default_reader_flush_timeout, and the collection configuration-level control parameter is FlushTimeoutSecs. Adjust these parameters if your application requires lower latency. Do not set these parameters to 0, because this may cause log truncation.

    Tag processing

    Tags processed by an extension are written to the tags structure of the data model instead of the content structure. This change reduces storage space:

    • Data consumption scenarios are affected. Handle compatibility in your downstream consumers.

    • Query scenarios are not affected.

    Container log collection path depth

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

    • Version 2.0 and later: The default maximum recursion depth for a folder is 0. If the collection path contains /**/, the depth is 10.

    • Versions earlier than 2.0: The default maximum recursion depth is 100.

    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 output is similar to the following:

    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

    Download the logtail.sh script again. Do not reuse an old copy of the 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;