AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 日志服务 数据采集 LoongCollector数据采集器（原Logtail） LoongCollector安装与管理（Linux） LoongCollector管理（Linux）

LoongCollector管理（Linux）

更新时间：
产品详情
我的收藏
重要

本文中含有需要您注意的重要提示信息，忽略该信息可能对您的业务造成影响，请务必仔细阅读。

安装LoongCollector后，您还需要了解如何管理LoongCollector的生命周期，运行配置等内容。

LoongCollector常用命令

启动LoongCollector

对采集性能有要求时，可修改启动参数配置文件（ilogtail_config.json）后再启动LoongCollector。
sudo /etc/init.d/loongcollectord start

停止LoongCollector

sudo /etc/init.d/loongcollectord stop

查看LoongCollector状态

sudo /etc/init.d/loongcollectord status #返回loongcollector is running表示启动成功。

查看LoongCollector版本

cat /usr/local/ilogtail/app_info.json #版本信息存储在loongcollector_version字段中。

重启LoongCollector

sudo /etc/init.d/loongcollectord restart

卸载LoongCollector

  1. 示例代码中${region_id}可使用cn-hangzhou替换，若想加快执行速度，请参考地域替换${region_id}为ECS所属地域。

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

  2. 执行卸载命令。

    chmod +x loongcollector.sh; sudo ./loongcollector.sh uninstall;

升级LoongCollector

升级包含LoongCollector版本升级与Logtail升级到LoongCollector两种情况，两种情况的升级命令相同。

LoongCollector版本升级/Logtail升级到LoongCollector

重要

LoongCollector在升级时停止运行，升级完成后自动启动。升级仅覆盖必要文件，配置文件和Checkpoint文件将被保留，确保升级期间日志不会丢失。

  1. 在服务器上执行下载命令获取最新安装包，示例代码中${region_id}可使用cn-hangzhou替换，若想加快安装包下载速度，请参考地域替换${region_id}为ECS所属地域。

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

  2. 执行升级命令：升级请使用upgrade命令。若使用install命令，将执行覆盖安装，丢失原配置。

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

  3. 若显示以下信息，则表示升级成功。 

    Upgrade loongcollector files successfully.
Starting loongcollector ...
Upgrade loongcollector successfully.

LoongCollector回滚到Logtail

说明

必须要重新下载logtail.sh脚本，不能使用原来的logtail.sh脚本。

  1. 在服务器上执行下载命令获取安装包，示例代码中${region_id}可使用cn-hangzhou替换，若想加快安装包下载速度，请参考地域替换${region_id}为ECS所属地域。

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

  2. 执行回滚命令。如需指定版本，如指定 1.8.7 版本，参考注释，根据实际情况替换版本号。

    chmod +x logtail.sh; sudo ./logtail.sh upgrade;
#chmod +x logtail.sh; sudo ./logtail.sh upgrade -v -v 1.8.7;

启动参数配置文件（ilogtail_config.json）

  • 文件描述：配置LoongCollector的启动参数，启动参数配置不合理会影响采集性能，配置错误可能导致采集异常问题发生。

  • 文件路径：/usr/local/ilogtail/ilogtail_config.json。

  • 使用场景：日志服务限制了LoongCollector的采集性能，以防消耗过多服务器资源，影响其他服务运行。当LoongCollector采集性能不满足要求时，可通过修改启动参数进行尝试。

  • 参数表：下表仅列出需要关注的常用启动参数，请根据需要新增或修改。未列出的参数请保持默认配置。

    ilogtail_config.json参数表

    参数

    类型

    说明

    示例

    cpu_usage_limit

    double

    CPU使用阈值，以单核计算。取值如下：

    • 取值范围：0.1~当前机器的CPU核心数

    • 默认值：0.4

    警告

    cpu_usage_limit为软限制，实际占用的CPU可能超过限制值，超限5分钟后将触发熔断保护自动重启。

    例如设置为0.4，表示日志服务将尽可能限制采集器的CPU使用为CPU单核的40%，超出后自动重启。

    一般情况下，通过极简模式采集日志时，单核处理能力约100 MB/s；通过完整正则模式采集日志时，单核处理能力约20 MB/s 。

    "cpu_usage_limit" : 0.4

    mem_usage_limit

    int

    内存使用阈值。取值如下：

    • 取值范围：128 MB ~ 8192 MB

    • 默认值：384 MB（主机），2048 MB（ACK组件）

    警告

    mem_usage_limit为软限制，实际占用的内存可能超过限制值，超限5分钟后将触发熔断保护自动重启。

    采集速率、监控目录和文件数量、发送阻塞程度与mem_usage_limit参数有关。更多请参见限制说明。

    "mem_usage_limit" : 384

    max_bytes_per_sec

    int

    每秒钟发送原始数据的流量限制。取值如下：

    • 取值范围：1024 Byte/s ~ 52428800 Byte/s

    • 默认值：20971520 Byte/s

      重要

      设置的值超过20971520 Byte/s（20MB/s），表示不限速。

    例如设置为2097152，表示发送数据的速率为2 MB/s。

    "max_bytes_per_sec" : 2097152

    process_thread_count

    int

    处理数据的线程数。 取值如下：

    • 取值范围：1~64

    • 默认值：1

    一般情况下，可以处理极简模式下24 MB/s的数据写入或完整正则模式12 MB/s的数据写入。默认情况下无需调整该参数取值。

    "process_thread_count" : 1

    send_request_concurrency

    int

    异步并发的个数。取值如下：

    • 取值范围：1~50

    • 默认值：20

    如果写入TPS很高，可以设置更高的异步并发个数。可以按照一个并发支持0.5 MB/s~1 MB/s网络吞吐来计算，实际根据网络延时而定。

    说明

    设置异步并发个数过高容易导致网络端口占用过多，需调整TCP相关参数。更多信息，请参见调整TCP相关参数。

    "send_request_concurrency" : 4

    buffer_file_num

    int

    限制缓存文件的最大数目。取值如下：

    • 取值范围：1~100

    • 默认值：25

    遇到网络异常、写入配额超限等情况时，采集器将实时解析后的日志写入本地文件（安装目录下）缓存起来，等待恢复后尝试重新发送。

    "buffer_file_num" : 25

    buffer_file_size

    int

    单个缓存文件允许的最大字节数。取值如下：

    • 取值范围：1048576 Byte ~ 104857600 Byte

    • 默认值：20971520 Byte

    buffer_file_size*buffer_file_num是缓存文件可以实际使用的最大磁盘空间。

    "buffer_file_size" : 20971520

    buffer_file_path

    String

    缓存文件存放目录。 默认值为空，即缓存文件存放于安装目录/usr/local/ilogtail下。

    当您设置此参数后，需手动将原目录下名为logtail\_buffer\_file_*的文件移动到此目录，以保证采集器可以读取到该缓存文件并在发送后进行删除。

    "buffer_file_path" : ""

    bind_interface

    String

    本机绑定的网卡名。默认值为空，自动绑定可用的网卡。

    如果设置为指定的网卡（例如eth1），则表示将强制使用该网卡上传日志。

    "bind_interface" : ""

    check_point_filename

    String

    checkpoint文件的保存路径， 默认值：/tmp/logtail_check_point。

    "check_point_filename" : /tmp/logtail_check_point

    check_point_dump_interval

    int

    更新Checkpoint文件的周期，默认值：900，单位：秒。即默认情况下每15分钟更新一次Checkpoint文件。

    "check_point_dump_interval" : 900

    user_config_file_path

    String

    配置文件的保存路径，默认为进程binary所在目录，文件名为user_log_config.json。

    "user_config_file_path" : user_log_config.json

    discard_old_data

    Boolean

    是否丢弃历史日志。默认值：true，表示丢弃距离当前时间超过12小时的日志。

    "discard_old_data" : true

    ilogtail_discard_interval

    int

    丢弃历史日志距离当前时间的阈值。默认值：43200（12小时），单位：秒。

    "ilogtail_discard_interval": 43200

    working_ip

    String

    默认值为空，表示自动从本服务器获取IP地址。修改后将以该值作为服务器的IP地址上报。

    "working_ip" : ""

    working_hostname

    String

    上报的本服务器的主机名。默认值为空，表示自动从本服务器获取主机名。

    "working_hostname" : ""

    max_read_buffer_size

    long

    每条日志读取的最大值。默认值：524288（512 KB），最大值：8388608（8 MB）。单位：Byte。

    如果您的单条日志超过524288 Byte，可修改此参数。

    "max_read_buffer_size" : 524288

    oas_connect_timeout

    long

    发起获取采集配置、访问密钥等请求时，连接阶段的超时时间。默认值：5，单位：秒。

    网络条件较差，建立连接时间过长时可修改此参数。

    "oas_connect_timeout" : 5

    oas_request_timeout

    long

    发起获取采集配置、访问密钥等请求时，整个请求阶段的超时时间。默认值：10，单位：秒。

    网络条件较差，建立连接时间过长时可修改此参数。

    "" : 10

    data_server_port

    long

    设置data_server_port为443后，将通过HTTPS协议传输数据到日志服务。

    "data_server_port": 443

    enable_log_time_auto_adjust

    Boolean

    设置enable_log_time_auto_adjust为true后，日志时间可自适应服务器本地时间。

    出于数据安全考虑，日志服务会对请求（包括Logtail发起的请求）所携带的时间进行校验，拒绝与日志服务端时间相差超过15分钟的请求。采集器发起请求时所携带的时间为服务器本地时间，当服务器本地时间被修改后（例如某些测试场景下需要调整本地时间为未来时间），请求将被拒绝，导致写入数据失败。您可以使用该参数实现日志时间自适应服务器本地时间。

    重要

    • 开启该功能后，日志时间将被加上日志服务端的时间与服务器本地时间的偏移量。由于偏移量只在请求被日志服务端拒绝时更新，因此可能出现日志服务端所查询到的日志的时间和日志实际的写入时间不一致的情况。

    • LoongCollector的部分逻辑依赖于系统时间的递增，建议在每次机器时间调整后重启采集器。

    "enable_log_time_auto_adjust": true

    accept_multi_config

    Boolean

    是否允许多个采集配置采集同一个文件。默认值：false，表示不允许。

    默认情况下，一个文件只能被一个采集配置采集，您可以通过该参数消除限制。每个采集配置的处理过程是独立的，当允许多个采集配置采集同一个文件时，需要消耗多倍的CPU、内存开销。

    "accept_multi_config": true

    enable_checkpoint_sync_write

    Boolean

    是否开启sync写功能。默认值：false，表示不开启。

    sync写功能主要用于搭配ExactlyOnce写入功能。开启ExactlyOnce写入功能后，采集器会在本地磁盘记录细粒度的Checkpoint信息（文件级别）。但出于性能考虑，默认写入Checkpoint时不会调用sync落盘，所以如果机器重启导致buffer数据来不及写入磁盘时，可能导致Checkpoint丢失。此时，您可以设置enable_checkpoint_sync_write为true，开启sync写功能。更多信息，请参见Logtail配置。

    "enable_checkpoint_sync_write": false

    enable_env_ref_in_config

    Boolean

    是否启用采集配置环境变量替换功能。默认值：false。

    开启该功能后，您可以在控制台的采集配置中使用${xxx}作为环境变量xxx的占位符。例如设置采集路径为/${xxx}/logs，环境变量为xxx=user，则生效的采集路径为/user/logs。

    如果配置中需要使用${、}，则您可以使用$${、$}进行转义。

    "enable_env_ref_in_config": false

    logreader_max_rotate_queue_size

    Int

    轮转队列最大长度。默认值：20。当日志采集发生阻塞或延时，待采集的文件会持有文件句柄在队列中等待。

    当采集延时，如果需要控制磁盘最大用量，可考虑减小该值。

    警告

    当延时的文件数超过该值时，将直接跳过新文件的采集。

    "logreader_max_rotate_queue_size" : 10

    data_endpoint_policy

    string

    对日志服务访问域名的切换策略。可选值如下：

    说明

    您可以在ilogtail_config.json文件的data_server参数中，查看是否已配置默认域名。

    • designated_first（默认）

      • 如果已指定某个地域的默认域名且默认域名可用，则系统优先使用默认域名。

      • 如果已指定某个地域的默认域名但默认域名不可用，则系统会自动选择一个可用域名。

      • 如果未指定某个地域的默认域名，则系统会自动选择一个可用域名。

    • designated_locked

      • 如果已指定某个地域的默认域名，不管其是否可用，系统都将只使用默认域名。

      • 如果未指定某个地域的默认域名，系统会自动选择一个可用域名。

    "data_endpoint_policy" : "designated_first"

    inotify_black_list

    Array<String>

    inotify监听黑名单，黑名单为完全匹配，此列表中的目录不会启用inotify监听。

    "inotify_black_list": ["/tmp"]

    host_path_blacklist

    String

    全局主机路径黑名单，黑名单为子串匹配。Linux系统下多个子串以半角冒号（:）分隔。

    例如"host_path_blacklist" : "/volumes/kubernetes.io~csi/nas-"表示禁止采集NAS挂载数据。

    "host_path_blacklist" : "/volumes/kubernetes.io~csi/nas-"

    LOGTAIL_LOG_LEVEL

    String

    日志打印级别，需通过环境变量进行配置。默认值：空，表示info，可选值trace、debug、info、warning、error和fatal。

    LOGTAIL_LOG_LEVEL=info

    FORCE_RELEASE_STOP_CONTAINER_FILE

    Boolean

    • 配置方式：仅支持通过环境变量方式进行配置。

    • 功能描述：当该参数设置为 true 时，采集器会在业务容器退出时立即释放容器文件句柄。此操作可防止因文件句柄未释放而导致容器无法正常退出。

    • 注意事项：

      • 此时无法保证容器内数据采集的完整性。

      • 建议在业务退出前增加几秒的延迟，以确保日志能够完整采集。

    "FORCE_RELEASE_STOP_CONTAINER_FILE" : "true"

  • 示例场景：以下列举一些常见的场景下的操作示例供参考：

日志传输网络延迟高、传输不稳定

发生日志丢失或重复发送，LoongCollector 发送日志时频繁重试，网络连接中断或波动频繁等现象。可能的原因是：

  • 网络带宽不足：当采集的日志量较大时，若网络带宽不足以支撑传输需求，会导致日志堆积、延迟增加。

  • 网络环境不稳定：跨区域、跨网络可能导致网络延迟或丢包。

解决方案

利用阿里云CDN边缘节点进行日志采集加速，相对公网采集在网络延迟、稳定性上具有很大优势。开启该功能将根据实际传输的数据量进行额外计费。

  1. 需要先打开Project的日志跨域传输加速功能。

  2. 停止LoongCollector：登录安装LoongCollector的服务器，执行sudo /etc/init.d/loongcollectord stop命令。

  3. 修改传输域名：替换/usr/local/ilogtail/ilogtail_config.json中data_servers参数下的endpoint_list参数的值为log-global.aliyuncs.com。这表明将数据传输所使用的域名变更为传输加速域名。

  4. 启动LoongCollector：执行sudo /etc/init.d/loongcollectord start命令。

单条日志过大被截断

发生单条日志长度过大，采集后日志被截断的现象，原因是每条日志读取的最大值默认为524288（512 KB），若超过该值日志服务将截断日志。多行日志按行首正则表达式划分后，每条日志大小限制仍为512 KB，若超限会被强制拆分为多条进行采集。

解决方案

  1. 在/usr/local/ilogtail/ilogtail_config.json中修改max_read_buffer_size参数的值，若该参数不存在则新增。该参数取值最大为8388608（8 MB）。

    请注意内存占用线性增长，需预留max_read_buffer_size*文件并发数内存。

  2. 重启LoongCollector：执行sudo /etc/init.d/loongcollectord restart命令。

传输时发生间隔15分钟以上日志丢失

发生采集日志时可以正常传输，但部分日志丢失，且丢失日志时间戳与当前日志服务服务端时间相差15分钟以上的现象，原因可能是出于数据安全考虑，日志服务会对请求（包括LoongCollector发起的请求）所携带的时间进行校验，拒绝与日志服务端时间相差超过15分钟的请求。当服务器本地时间被修改后（例如某些测试场景下需要调整本地时间为未来时间），则导致请求被拒绝，写入数据失败。

解决方案

  1. 在/usr/local/ilogtail/ilogtail_config.json中修改enable_log_time_auto_adjust参数的值为true，若该参数不存在则新增。设置后日志时间可自适应服务器本地时间。

    开启该功能后，日志时间将被加上日志服务端的时间与服务器本地时间的偏移量。由于偏移量只在请求被日志服务端拒绝时更新，因此可能出现日志服务端所查询到的日志的时间和日志实际的写入时间不一致的情况。

  2. 重启LoongCollector：执行sudo /etc/init.d/loongcollectord restart命令。

切换至其他地域Project

由于某些原因，在服务器上采集的日志需要存储到新的Project中。

解决方案

  1. 若需要复用采集配置，请先保存采集配置文件中内容，卸载操作会删除该文件。

  2. 卸载服务器上的LoongCollector。

  3. 根据新Project与服务器的关系，选择对应的LoongCollector安装方案。

  4. 如果要将历史数据也一并转移到新Project，此处提供两种方式：

日志传输延时过长优化

发生日志服务的日志时间戳和服务器生产日志的时间相差在三秒以上的现象，原因可能是：

  • 同时采集的文件数超过100个或者监控的目录下的文件数超过5000个，占用大量内存。

  • 日志数据流量大（例如极简模式下超过2 MB/s，正则模式下超过1 MB/s），CPU占用率过高。

    开通CloudLens for SLS，在采集监控可以查看当前主机的CPU占用率。

  • LoongCollector发送数据到日志服务的速率超过10MB/s。

    开通CloudLens for SLS，在采集监控可以查看当前主机的采集速率。

解决方案

添加或修改ilogtail_config.json中参数取值，并重启LoongCollector使修改生效。不同采集速率下的建议值参考如下：

说明

按表格中的采集速率大于40 MB/s列配置启动参数时，采集性能已接近极限。

参数

描述

采集速率大于10 MB/s

采集速率大于20 MB/s

采集速率大于40 MB/s

cpu_usage_limit

CPU使用阈值，以单核计算。

  • 取值范围：0.1~当前机器CPU核心数

  • 默认值：0.4

0.4表示日志服务将尽可能限制采集器对CPU单核使用不超过40%，超出后LoongCollector自动重启。

该项为软限制，实际占用的CPU可能超过限制值，超限5分钟后将触发熔断保护自动重启。

1

2

4

mem_usage_limit

内存使用阈值。

  • 取值范围：128 MB ~ 8192 MB

  • 默认值：384 MB

采集速率、监控目录和文件数量、发送阻塞程度与该参数有关。更多请参见限制说明

该项为软限制，实际占用的内存可能超过限制值，超限5分钟后将触发熔断保护自动重启。

1024

2048

4096

process_thread_count

采集器处理数据的线程数。

  • 取值范围：1~64

  • 默认值：1

单线程可以处理极简模式下24 MB/s的数据写入或完整正则模式12 MB/s的数据写入。默认情况下无需调整该参数取值。

2

4

8

send_request_concurrency

异步并发的个数。

  • 取值范围：1~50

  • 默认值：20

如果写入TPS很高，可以设置更高的异步并发个数。可以按照一个并发支持0.5 MB/s~1 MB/s网络吞吐来计算，实际根据网络延时而定。

20

40

80

其他常用配置文件

LoongCollector运行时一系列配置文件与信息记录文件如下：

LoongCollector采集配置文件（user_log_config.json）

  • 描述：文件记录LoongCollector从日志服务获取的采集配置信息，每次采集配置更新时会同步更新该文件。除手动配置AccessKey信息、数据库密码等敏感信息外，不建议修改该文件。

  • 路径：/usr/local/ilogtail/user_log_config.json。

  • 使用场景：可通过查看该文件确认采集配置是否已经下发到服务器。若该文件存在，且内容与日志服务上的采集配置一致，表示采集配置已下发。

AppInfo记录文件（app_info.json）

  • 描述：app_info.json文件记录LoongCollector的启动时间、获取到的IP地址、主机名等信息。该文件仅作记录，任何修改操作均不会生效。

  • 路径：/usr/local/ilogtail/app_info.json。

  • 使用场景：可查看日志服务采集时识别到的服务器ip信息，判断与日志服务控制台中IP型机器组内IP信息是否一致，一般用于解决IP型机器组心跳失败问题。

    如果已在服务器的/etc/hosts文件中设置了主机名与IP地址绑定，则自动获取绑定的IP地址。如果没有设置主机名绑定，会自动获取本机的第一块网卡的IP地址。若设置了ilogtail_config.json中的working_ip参数，则以working_ip值作为服务器的IP地址。

LoongCollector运行日志（loongcollector.LOG）

  • 描述：loongcollector.LOG文件记录了LoongCollector的运行日志，日志级别从低到高分别为INFO、WARN和ERROR。

  • 路径：/usr/local/ilogtail/loongcollector.LOG。

  • 使用场景：如果采集异常，请先使用LoongCollector运行情况诊断与监控排查错误，根据日志采集错误类型排查具体的错误类型和LoongCollector运行日志排查问题。

用户ID文件

  • 描述：包含日志采集到的Project所属的阿里云主账号ID信息，文件名即账号ID，无需后缀，用于标识该账号有权限访问、采集这台服务器的日志。

  • 路径：/etc/ilogtail/users/{阿里云账号ID}。

  • 使用场景：只有在采集非本账号ECS、自建服务器、其他云厂商服务器日志时需要配置用户ID。多个账号对同一台服务器进行日志采集时，支持在同一台服务器上创建多个用户ID文件。

用户自定义标识文件

  • 描述：用于配置用户自定义标识，作为用户自定义标识机器组的内容，协助日志服务发现服务器上的LoongCollector并建立心跳。

  • 路径：/etc/ilogtail/user_defined_id。

  • 使用场景：使用用户自定义机器组时需要配置，了解更多信息请参考机器组与LoongCollector采集配置关联指南。

CheckPoint文件

  • 描述：checkpoint机制用于记录日志服务当前采集位置以确保日志完整性。

  • 路径：默认为/tmp/logtail_checkpoint。

  • 使用场景：可参考限制说明修改启动参数文件进行管理。

常见问题

服务器无法连接外部网络时如何升级

  1. 在需要升级LoongCollector的服务器上执行uname -m查看系统架构后，在可以访问公网的服务器上选择对应命令执行：${region_id}需替换为Project所属地域的地域。

    • ARM架构：

      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;

    • x86-64架构：

      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;

  2. 将安装脚本和安装包拷贝至需要升级LoongCollector的服务器上后，执行命令：

    chmod +x loongcollector.sh;./loongcollector.sh upgrade-local;
上一篇：LoongCollector安装（Linux）下一篇：LoongCollector安装与管理（Kubernetes）