LoongCollector管理（Windows）

LoongCollector常用命令

{
"loongcollector_version" : "3.1.4.0"
}

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

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

• 文件路径：C:\Program Files\Alibaba\Logtail\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文件的保存路径， 默认值：C:\LogtailData\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"
  enable_root_path_collection	boolean	从系统安全角度出发，LoongCollector默认不允许采集Windows根目录（例如D:\log*）下的文件，或监控文件路径中根目录带有通配符（例如D:\app*\log\）的路径,如需采集这些文件或监控对应的目录，需要配置该参数。	"enable_root_path_collection" : true

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

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

  原因分析

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

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

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

  解决方案

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

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

  2. 停止LoongCollector：登录安装LoongCollector的服务器，手动停止LoongCollector。

  3. 修改传输域名：替换C:\Program Files\Alibaba\Logtail\ilogtail_config.json中data_servers参数下的endpoint_list参数的值为log-global.aliyuncs.com。这表明将数据传输所使用的域名变更为传输加速域名。

  4. 手动启动LoongCollector。

  单条日志过大被截断

  原因分析

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

  解决方案

  1. 在C:\Program Files\Alibaba\Logtail\ilogtail_config.json中修改max_read_buffer_size参数的值，若该参数不存在则新增。该参数取值最大为8388608（8 MB）。

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

  2. 手动重启LoongCollector。

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

  原因分析

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

  解决方案

  1. 在C:\Program Files\Alibaba\Logtail\ilogtail_config.json中修改enable_log_time_auto_adjust参数的值为true，若该参数不存在则新增。设置后日志时间可自适应服务器本地时间。

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

  2. 手动重启LoongCollector。

  切换至其他地域Project

  原因分析

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

  解决方案

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

  2. 卸载服务器上的LoongCollector。

  3. 重新安装LoongCollector。

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

     • 先下载日志到本地后，再使用导入历史日志文件将日志传输到新Project。

     • 通过数据加工将旧Project中数据复制到新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运行时一系列配置文件与信息记录文件如下：