极速导入，便捷无忧！LoongCollector 一次性文件采集能力上线

2026-03-23 4 纸飞机账号购买

你有没有碰到过这种情形：要求迅速迁移过往日志，进行补录数据，处理一批静态文件，然而却因传统采集工具那种“长期监控，仅仅采集增量数据”的状况而感到苦恼呢？

LoongCollector 是阿里云日志服务推出的一款集性能、稳定性和可编程性于一身的新一代数据采集器，专为构建下一代可观测 Pipeline 设计。LoongCollector扩展融合了可观测性技术栈，改变传统日志采集器的单一场景限制，支持Logs、Metrics、Traces、Events、Profiles 的采集、处理、路由、发送等功能。（商业版：https://help.aliyun.com/zh/sls/what-is-sls-loongcollector/，开源版：https://github.com/alibaba/loongcollector。）

LoongCollector所推出的一次性方面的文件采集，是专门针对这类需求而进行量身打造的一种解决方案，不同于常规的持续采集，一次性文件采集的配置在启动之后会一次性去扫描匹配到文件，接着完成读取操作，随后自动结束，并不需要人工在一旁盯守，它适用于历史文件迁移、数据补录以及临时批处理等场景，既能够节省资源，又可以确保数据完整地上传。

稳定、可控、可追踪的云端批量自动化数据采集

在一次性文件采集能力推出前，LoongCollector（及其前身 iLogtail）也提供过“历史文件采集”方案（参考导入历史日志：https://help.aliyun.com/zh/sls/import-historical-logs）。相比旧方案，新版一次性文件采集配置更加简单快捷，具备更强的批量化能力与更清晰的生命周期，并通过更细粒度的 checkpoint 提升了稳定性与可观测性。

新推出的一次性采集，促使静态数据采集从那种单机状态下的手动操作，转变成为云端环境里的批量自动化操作，而且变得更加稳定，更加可控，更加可追踪。那么，这些优势究竟是通过怎样的方式得以实现的呢？接下来，就来进行逐一的介绍。

1.其一，运行逻辑揭秘，一点一点一，一次性，也就是所谓OneTime采集配置，有此情形。

什么是“一次性（OneTime）”采集配置

LoongCollector的那个用于采集的流水线，也就是pipeline，能够划分成两类。

两类流水线的适用场景可概括如下：

如何区分 OneTime 采集配置

于客户端那一侧，OneTime流水线之中的“开关”，乃是global.ExcutionTimeout。

对比示例如下：

# 普通文件采集
enable: true
inputs:
  - Type: input_file
    FilePaths:
      - /var/log/*.log
flushers:
  - Type: flusher_stdout
    OnlyStdout: true
    Tags: true
# 一次性文件采集
enable: true
global:
  ExcutionTimeout: 3600
inputs:
  - Type: input_static_file_onetime
    FilePaths:
      - /var/log/history/*.log
flushers:
  - Type: flusher_stdout
    OnlyStdout: true
    Tags: true

OneTime 的执行窗口与过期机制

不能够不把一次性采集流水线“讲透”，这就需要在同一时间，将服务端那边的配置生命周期，以及控制台侧相对应的配置生命周期，和客户端那边的执行情况，还有客户端侧的可靠性机制，全都对齐起来。能够把此种情况理解成：

服务端：下发窗口、执行窗口、保留期限

一次性采集配置在控制台侧通常包含三个关键时间点：

配置下发窗口：只针对在配置创建之后的一段特定时间内，有过上报心跳行为的机器去下发配置，此时间为5分钟，若更新配置则会刷新该窗口。配置执行窗口：在配置生效之时起，配置能够允许运行的最长时间是配置所设定的执行超时时间，也就是global.ExcutionTimeout，其默认时间是10分钟，时间范围处于10分钟至1周之间。配置保留期限：服务端方面会保留配置一段时长，目的是用于进行追溯或者复用，此时长为7天。

倘若在创建并且配置之后，才将机器添加进机器组，那么极有可能已然错失了下发窗口；当数据量处于很大的状况时，务必要预先把ExcutionTimeout进行调大，要不然就会出现配置尚未采集完毕，便进而抵达执行窗口时间上限的情况，最终致使数据采集中断。

在客户端这边，有着这样的执行情况，关于过期超时范围以及默认值，global.ExcutionTimeout 的单位是秒，其范围被限制在 600 到 604800 之间（也就是 10分钟至1周）。存在着过期行为，对于 OneTime配置而言客户端会去计算并且记录下过期时间（start + ExcutionTimeout）。当配置过期的时候，客户端将会清理过期配置文件并且移除其状态记录。当处 OneTime 配置更新之际，客户端会依据以下诸般因素来判定是否需要“重新执行一回”，此判定关乎的便是配置更新是否“重跑”（旨在避免误采以及重复采）：当 global.ForceRerunWhenUpdate 取值为 true 之时，一旦配置出现任何哪怕极其细微的变化，便会被强制要求重跑；而当 global.ForceRerunWhenUpdate 取值为 false（此为默认情形）之时，将会以 inputs 的 hash 以及 ExcutionTimeout 是否产生变化作为判断依据——要是这两者均未发生变化，那么便不会进行重跑而是继续沿用原本的过期时间，如果情况并非如此，即两者之中有任何一个发生了变化，那么便会按照“新的一次性配置”来予以处理。

OneTime的设计目标里有一个是“避免重复去执行相同的配置”，所以更新策略会尽可能地达成可控重跑。

1.1.2 一次性文件采集

一次性文件采集的“快照语义”

对输入的静态文件进行一次性操作，其核心语义能够归纳为三点：

开启之时一次性发觉文件，开启之际扫描匹配路径，把“当时现存的匹配文件清单”固定到checkpoint，后续增添的文件不会被归入此次采集对象，仅读取开启时刻的文件规模，每个文件会记载一个初始大小，采集进程里即便文件有加写操作，此次也仅读取至初始大小为止，以此避免边采集边写入所导致的不可控重复及漏采现象。支持进行轮转定位，文件fingerprint含有dev、inode、sig_hash、sig_size等信息，其中sig_hash/sig_size源自文件开头最多1024字节的签名，当文件轮转致使路径发生变化时，客户端会试着在目录中依据dev+inode进行查找并持续读取，尽可能防止漏采。

一次性文件采集的可靠性（checkpoint 机制）

文件采集若是一次性的，那么会借助checkpoint来记录，记录的内容是“配置级别状态 + 文件级别进度”，其目的在于支持重启，支持升级，支持异常恢复，并且要尽可能地防止出现重复采集的情况。

配置级 checkpoint

这个文件是用来记录核心信息的，这些核心信息是关于OneTime配置的，像config_hash、expire_time、inputs_hash、excution_timeout等等，它对恢复OneTime配置的过期时间以及更新策略判断有作用，是在重启之后发挥作用的，它的路径一般处于 /etc/ilogtail/checkpoint/onetime_config_info.json。

文件级 checkpoint

记载一次性文件采集执行进度，以及每个文件状体的那个文件，其路径一般处于这样的位置：/etc/ilogtail/checkpoint/input_static_file/{config_name}@0.json。

字段说明（与实际落盘 JSON 对齐）：

{
  "config_name" : "xxxx",
  "expire_time" : 1768550944,
  "file_count" : 1,
  "files" : 
    [
      {
        "dev" : 2051,
        "filepath" : "/var/log/tmpfs.log",
        "finish_time" : 1768550345,
        "inode" : 2888304,
        "size" : 1282,
        "start_time" : 1768550345,
        "status" : "finished"
      }
    ],
  "finish_time" : 1768550345,
  "input_index" : 0,
  "start_time" : 1768550344,
  "status" : "finished"
}

资源占用与吞吐控制

C++ 实现的原生输入插件，进行一次性文件采集，此插件和常规文件采集共同使用 reader 体系，其具备比较不错的吞吐能力，单线程采集单行文本日志时，理论上的极限性能能够达到 300MB/s；与此同时，对于资源占用，也做出了“可控”的约束：

快速体验

阿里云所提供的日志服务，已经上线了具备特定性质的一次性进行文件全面采集工作的能力，仅仅需要通过三个步骤，便能够去体验该项全新的功能：

1. 进入 SLS 控制台，于 Logtail 配置界面之中，挑选“一次性配置”，而后点击“添加 Logtail 配置”。

2. 选择“一次性文件采集-主机”。

3. 填写文件采集配置（与普通文件采集的配置习惯一致），按需配置处理插件后保存。更详细的说明和参数解释可以参考官网文档：https://help.aliyun.com/zh/sls/one-time-collection-of-host-te... 。

保存后即可看到数据被采集上来：

并可在配置详情里查看完整的采集配置：

最佳实践建议3.1 场景一：大规模机器组补采大量文件

假设场景：

如果直接使用默认参数下发一次性文件采集配置，可能出现：

写入的速率在瞬间急剧地冲高起来，进而触发了 shard write quota 出现报错的情况；补采的流量对日常采集的流量进行了挤占；发送端出现积压致使 OneTime 任务在 ExcutionTimeout 这个时间段之内没有办法完成。

建议做两步控制：

第一步：限流（MaxSendRate）

透过适用的quota做大致的估量，剩余能够写入的大概是(256乘以5减去1000乘以1等于280)MB每秒，平均分配到每一台大约为0.28MB每秒（约等于286KB每秒约等于286720B每秒），进行取整大约是290000B每秒。可以把MaxSendRate设置为约为290000（B每秒）来实行限流。

第二步：放大执行超时（ExcutionTimeout）

在发送速率为二百八十六千字节每秒的情况下，补采十吉字节至少大约需要十吉字节除以二百八十六千字节每秒，约等于三万六千六百六十三秒，约等于十点二小时。建议把执行超时设置为八万六千四百（约一天），给采集留出充足余量。

总结，执行超时时间为86400加上最大发送速率为290000，这样就能够在尽可能不干扰在线日常采集的情况下达成大规模补采。

3.2 场景二：只补采文件中某个时间段的数据

假设场景（不考虑配额，仅讨论“避免重复”）：

一次性文件采集系以“文件快照”作为单位来执行，要是直接进行补采，极有可能会将已然上报过的时间段一同再次采集。

要解决这个问题，思路是这样的：在OneTime采集流水线里，添加时间戳过滤处理插件processor_timestamp_filter_native，必要的时候，要配合processor_parse_json_native以及processor_parse_timestamp_native一起使用，只需保留目标时间区间之内的事件，这样就能达成“精准补采”的目的。

控制台配置示意图如下：

3.3 场景三：需要修改一次性采集配置（避免“脏数据”混入）

一次性进行采集，其特点是“下发即执行”，要是首次配置的时候，存在处理逻辑方面的错误，即便马上进行更新配置，也极有可能已经产生了一部分并非预期的数据，进而使得新旧数据混杂在一起，对分析造成影响。

建议做法：

先是头一回创建 OneTime 配置，却发觉产出跟预期不一致；接着去更新 OneTime 配置（能够设置 ForceRerunWhenUpdate: true 来强制重新运行，中断先前的采集任务），进而验证新采集到的数据格式是不是正确；要是不满足要求的话，能够再三反复进行重试。利用查询语句筛选出不符合预期的数据，并且经由日志服务软删除加以清理（示例文档：日志服务软删除：）https://help.aliyun.com/zh/sls/soft-delete）。

可只留存与“最终正确配置”相对应的采集结果，如此这般，以防止对后续的分析造成干扰。

总结

一次性文件收集适宜历史数据挪动、断网补充采集、临时批处理等情景，配置下发之后依照“启动时刻文件快照”开展执行，搭配checkpoint保障具备可恢复性、可观测性，再联合ExcutionTimeout与MaxSendRate做好“时长加流量”双重兜底，便可在不搅扰线上不断采集的状况下，将静态数据安稳补齐的。欢迎各位试用并给予反馈！