一、 FileScout 简介

FileScout 是基于 Filebeat 二次开发，增加了 output http 和定时删除过期日志(过期时间可自定义)的日志上传工具

FileScout 主要用于将 DT 服务端 SDK 写入的日志数据实时的导入 DT server 后台，可以自定义监控服务器日志目录，当目录下有新文件产生时，会实时发送至 DT server 后台

适用用户群体：

基于各方面原因和考虑，不方便使用客户端 SDK 上报的用户
已经使用服务端 SDK 保存 DT 格式数据的用户
对传输效率有一定要求的用户

二、下载 FileScout

当前版本号： 1.0.1

发布/更新时间：2025.09.05

amd：https://storage.googleapis.com/datatower-backend-storage/dt-sdk/filescout/filescout-linux-amd64.zip
arm：https://storage.googleapis.com/datatower-backend-storage/dt-sdk/filescout/filescout-linux-arm64.zip
mac m芯片：https://storage.googleapis.com/datatower-backend-storage/dt-sdk/filescout/filescout-mac-mchip.zip
mac intel芯片：https://storage.googleapis.com/datatower-backend-storage/dt-sdk/filescout/filescout-mac-intel.zip
windows：https://storage.googleapis.com/datatower-backend-storage/dt-sdk/filescout/filescout-windows.zip

三、使用前准备(请仔细阅读)

确认上传文件的存放目录，配置后 FileScout 会自动监测目录下文件的变化
请勿对监控目录下的文件进行重命名，这会导致重新上传，有可能会造成数据重复
请勿直接使用 kill -9 强杀进程, 这样程序无法正常结束正在处理的工作
确保 FileScout 可执行文件和配置文件在同一目录下
若不使用 DT 的服务端 SDK, 自行写入文件, 请确保文件名和 SDK 写入的文件名格式一致, 文件内容确保单行就是一个有效的 json, FileScout 不对数据是否在业务上合法进行任何校验
请勿删除 FileScout 目录下的文件和文件夹
请根据磁盘空间和 log 文件大小合理配置文件过期时间用以执行定时删除任务

四、 FileScout 安装和使用

下载对应系统的压缩包，并解压，修改目录下 filebeat.yml 配置文件后直接执行 ./filescout start 即可
停止程序可以使用 ./filescount stop
输入 ./filescout restart 可以重启项目
定时删除任务一个小时执行一次, log 的过期时间可以在配置项中配置
Windows 版本也需要在命令行中使用

五、配置文件指南

5.1 基本配置模板

请基于配置模板进行修改避免 yml 的格式错误问题, 请勿删除 - 符号

filebeat.inputs:
  - type: log
    enabled: true
    paths:
      - "/path/to/your/log/dir1/*.log"
      - "/path/to/your/log/dir2/*.log"
    json.key_under_root: true
    json.overwrite_keys: true
  - type: log
    enabled: false
    paths:
      - "/path/to/your/log/dir3/*.log"
      - "/path/to/your/log/dir4/*.log"
    json.key_under_root: true
    json.overwrite_keys: true
output.http:
  url: "https://{api_server_url}/sync"
  retry_interval: 5
  batch_size: 100
  app_id: "dt_xxxxxxxx"
  token: "xxxxx"
sweeper:
  unit: "hour"
  offset: 1

5.2配置参数说明

5.2.1 配置项目列表

配置项	类型	必填	说明
filebeat.inputs	List[Object]	是	数据源列表
output.http	Object	是	上报相关配置
sweeper	Object	否	定时删除配置, 默认值为 24 小时

5.2.2 数据来源 (filebeat.inputs)

配置项	类型	示例	必填	说明
type	String	log	是	说明数据源类型, 暂时只支持 DT 服务端 SDK 的 log 文件
enabled	Bool	true/false	是	该数据源是否启用, false 不会发送目录下数据
paths	List[String]		是	监控的日志目录
json.key_under_root	Bool		是	请勿修改, 将 json 序列化后的 key 放入根 output 对象下
json.overwrite_keys: true	Bool		是	请勿修改, 覆盖之前的同名 key
close_inactive	String	1m	是	主动释放大于这个时间未变更的文件的文件描述符
close_removed	Bool	true/false	是	主动释放被删除的文件的文件描述符, 若该项为 false, 则 clean_removed 也必须为 false
clean_removed	Bool	true/false	是	主动从注册表中清除被删除的文件

5.2.3 上报相关 (output.http)

配置项	类型	示例	必填	说明
url	String		是	上报地址，"https://report.roiquery.com/sync"
retry_interval	Int	5	是	上报请求失败后重试的间隔秒数
batch_size	Int	100	是	将多少个 event 合并上报, 减少请求次数
app_id	String		是	和数据上报的 app_id 无关, 只用作校验, 只需要满足 DT 后台存在该 app_id 并启用即可
token	String		是	线上服务使用的校验 token，请联系DT工作人员进行申请

5.2.4 定时删除相关 (sweeper)

配置项	类型	示例	必填	说明
unit	String	"hour"	否	定时删除的单位, 仅支持 "hour" 和 "day"
offset	Int	5	否	定时删除的偏移量, 正整数, 超过 unit * offset 的 log 文件会被视作过期被删除

sweeper 可以不填写, 默认 unit 为 "hour", offset 为 24, 即 24 小时
若 sweeper 填写错误, 会使用默认配置
定时删除任务为每隔一个小时一次执行一次, 在 FileScout 启动时会执行一次
例如 FileScout 启动时间为 5:01pm, 启动时执行完删除任务后, 下一次删除任务的启动时间是 6:01pm

使用示例:

unit 为 "hour", offset 为 3, 定时删除启动时间为 12 号 5:30pm, 则 12 号 2:30pm 之前的文件都会被删除
unit 为 "day", offset 为 3, 定时删除启动时间为 12 号 5:30pm, 则 9 号 5:30pm 之前的文件都会被删除

数据导入