All Products
Search
Document Center

:Self-service diagnostic tool of Logtail

Last Updated:Mar 11, 2025

If you encounter anomalies when using Logtail to collect logs, you can use the self-service diagnostic tool to quickly locate and resolve issues.

Usage notes

  • This tool is available only for Linux servers.

  • It uses the curl tool to check network connectivity. Ensure that the curl tool is installed on the target server.

  • Logtail collects only incremental logs. If a log file on a server is not updated after the applied Logtail configuration is delivered to the server, Logtail does not collect logs from the file. For more information, see Read log files.

  • By default, a file can match only one Logtail configuration for collection. If you want a log to be collected multiple times, see How do I collect multiple copies of logs in a file?

Diagnostic procedure

image

Procedure

  1. Log on to the Linux server where Logtail is installed and run the following command to download the diagnostic tool.

    wget http://logtail-release.oss-cn-hangzhou.aliyuncs.com/linux64/checkingtool.sh -O checkingtool.sh
  2. Run the following command to execute the diagnostic tool.

    chmod 744 ./checkingtool.sh
    ./checkingtool.sh
    sh checkingtool.sh
  3. After running the diagnostic tool, the system returns the following information. Follow the on-screen instructions to select a language.

    [Info]:     Logtail checking tool version : 0.3.1
    [Input]:  Please choose language 请选择语言 : 
                    1. 中文. 
                    2. English. 
            语言 :
  4. The system then prompts you to choose a check procedure.

    [Input]:  please choose which type you want to check : 
                    1. MachineGroup heartbeat fail. 
                    2. MachineGroup heartbeat is ok, but log files have not been collected. 
            Type :
    • 1: Select this option to inspect the machine group.

    • 2: Select this option to verify the Logtail configuration.

    Check the machine group

    The self-service diagnostic tool of Logtail will perform the following checks:

    1. Check basic information.

      • Logtail installation

      • Logtail running status

      • Secure Sockets Layer (SSL) status

      • Network connectivity to Simple Log Service

      [Info]:     Check Logtail install files
      [Info]:     Install file: ilogtail_config.json exists.                          [ OK ]
      [Info]:     Install file: /etc/init.d/ilogtaild exists.                         [ OK ]
      [Info]:     Install file: ilogtail exists.                                      [ OK ]
      [Info]:     Bin file: /usr/local/ilogtail/ilogtail_2.0.8 exists.                [ OK ]
      [Info]:     Logtail version : 2.0.8                                             [ OK ]
      
      [Info]:     Check Logtail running status
      [Info]:     Logtail is runnings.                                                [ OK ]
      [Info]:     Check network status
      [Info]:     Logtail is using ip: 172.31.0.246
      [Info]:     Logtail is using UUID: D1BA8F5A-FA52-11EF-8935-00163E4C****
      [Info]:     Check SSL status
      Redirecting to /bin/systemctl status iptables.service
      Unit iptables.service could not be found.
      [Info]:     SSL status OK.                                                      [ OK ]
      [Info]:     Check logtail config server
      [Info]:     config server address: http://logtail.cn-hangzhou-intranet.log.aliyuncs.com
      [Info]:     Logtail config server HTTP OK                                       [ OK ]
      [Info]:     Logtail config server HTTPS OK                                      [ OK ]
    2. Check whether your server is an Elastic Compute Service (ECS) instance and belongs to the same account as the current project.

      • If yes, enter y to proceed to the next step.

      • If no, enter N. The diagnostic tool returns the user identifier configured on the server. If your Alibaba Cloud account ID is not included, reconfigure a user identifier.

        [Input]:  Is your server Alibaba Cloud ECS belongs to the same account of the current SLS Project ? (y/N)n
        [Info]:     Check aliyun user id(s)
        [Info]:     aliyun user id : 198********815 .                                 [ OK ]
        
        [Input]:  Is your project owner account ID among the above IDs ? (y/N)n
        [Error]:    please configure user IDs (account IDs), this doc will help
                    [ https://www.alibabacloud.com/help/doc-detail/49007.htm ]          [ Error ]
    3. Check whether your project's region matches the region selected during Logtail installation.

      • If yes, enter y to proceed to the next step.

      • If no, enter N. The diagnostic tool prompts you to reinstall Logtail or recreate the project to ensure that the project's region matches the region selected during Logtail installation. For more information, see Install Logtail on a Linux server.

        [Input]:  please make sure your project is in this region : { cn-hangzhou } (y/N) :n
        [Error]:    please reinstall your Logtail or recreate your project to
                    make sure your project is located in the same region with your Logt [ Error ]
    4. Check whether the IP address or custom ID in your machine group matches the one shown in the returned message.

      • If yes, enter y. The diagnostic tool will generate a report. If the issue persists, copy the output report and submit a ticket.

      • If no, enter N. The diagnostic tool prompts you to correct the IP address or custom ID in the machine group. For more information, see Modify a machine group.

        [Input]:  please make sure your machine group's ip is same with : { 172.31.0.246 } or your machine group's userdefined-id is in : { user-defined-linux-1 } (y/N) :n
        [Error]:    please correct your machine group's ip or userdefined-id,
                    save the configuration, wait 1 minute and check again               [ Error ]

    Check the Logtail configuration

    The self-service diagnostic tool of Logtail will perform the following checks:

    1. Ensure that the heartbeat status of your machine group is normal and the IP address in the machine group matches the IP address displayed in the returned message.

      • If yes, enter y to proceed to the next step.

      • If no, enter N. The diagnostic tool will prompt you to return to check the machine group.

        [Input]:  please make sure your machine's heartbeat is ok and machine group's ip is same with : { 172.31.0.246 } (y/N) :n
        [Error]:    please rerun the script and choose type 1 to check machine group's  [ Error ]
    2. Verify that your Logtail configuration is applied to the machine group.

    3. Check whether the log file path in the Logtail configuration is valid.

      When checking, enter the full path of the log file you want to check. If no file is matched, verify that the specified path can match the file.

      If the configuration is invalid, modify the Logtail configuration and wait about 1 minute before rerunning this script to check again.

      [Input]:  please input your log file's full path (eg. /var/log/nginx/access.log) : /var/log/nginx/access.log
      [Info]:     Check specific log file
      [Info]:     Check if specific log file [ /var/log/nginx/access.log ] is included by user log config.
      [Info]:     Specific log file exists.                                           [ OK ]
      [Error]:    No match config for your log file.                                  [ Error ]
      [Suggestion]:  Please check collection config is created in SLS Project/Logstore and make sure you have applied config to your machine group
    4. If the issue persists, copy the diagnostic report and submit a ticket.

      [Input]:  please make sure all the check items above have passed. If the problem persists, please copy all the outputs and submit a ticket in the ticket system. : (y/N)y
      [Info]:     Check system support
      [Info]:     Check system support OK.                                            [ OK ]
      
      [Info]:     Check Logtail install files
      [Info]:     Install file: ilogtail_config.json exists.                          [ OK ]
      [Info]:     Install file: /etc/init.d/ilogtaild exists.                         [ OK ]
      [Info]:     Install file: ilogtail exists.                                      [ OK ]
      [Info]:     Bin file: /usr/local/ilogtail/ilogtail_2.0.8 exists.                [ OK ]
      [Info]:     Logtail version : 2.0.8                                             [ OK ]
      ......
      ......

Run a quick check

During a quick check, the diagnostic tool returns the user identifier (Alibaba Cloud account ID) and the custom ID of the machine group configured on the server. No alert is triggered if either is missing. If settings are configured, ensure the user identifier or custom ID matches the returned message. If they differ, reconfigure the user identifier and create a machine group with a custom ID.

Run the following command to perform a quick check:

./checkingtool.sh --logFile [LogFileFullPath]

If the specified log file passes the check and the Logtail runtime environment is normal, we recommend that you view the error logs of the related parameters in the Simple Log Service console. For more information, see How do I view Logtail collection errors?

Common parameters of the diagnostic tool

Common parameters

Description

--help

Views the help documentation.

--logFile [LogFileFullPath]

Checks whether Logtail collects logs from the path specified by LogFileFullPath and checks the basic Logtail runtime environment, such as the integrity of installation files, running status, Alibaba Cloud account ID, and network connectivity.

--logFileOnly [LogFileFullPath]

Checks whether Logtail collects logs from the path specified by LogFileFullPath.

--envOnly

Checks the attributes of the runtime environment of Logtail.

Common issues of Logtail collection exceptions

Use the self-service diagnostic tool to identify and resolve errors in log collection. The table below outlines common causes of Logtail collection errors and their solutions.

Common causes

Solutions

Installation files are missing

Reinstall Logtail.

Logtail is not running

Run the /etc/init.d/ilogtaild start command to start Logtail.

Multiple Logtail processes exist

  1. Run the /etc/init.d/ilogtaild stop command to stop Logtail.

  2. Run the /etc/init.d/ilogtaild start command to start Logtail.

Port 443 is disabled

Configure the firewall to enable port 443.

The configuration server cannot be found

Check whether Logtail is correctly installed. If it isn't, rerun the installation command. For information about how to install Logtail and check the Logtail status, see Install Logtail on a Linux server.

The user configuration does not exist

Check whether the following operations are performed:

  1. A Logtail configuration is created.

  2. The server is included in the machine group.

  3. The Logtail configuration is applied to the machine group.

The specified log file cannot be found

Check whether the Logtail configuration is valid.

The specified log file is matched by more than one Logtail configuration

If a log file matches multiple Logtail configurations, Logtail randomly selects one. We recommend using only one configuration for each log file.