Skip to main content

持久化访问日志

自 JuiceFS 企业版 5.3.8 版本开始,JuiceFS 客户端可以将文件系统的所有操作(如读写、创建、删除等)持久化记录到访问日志(access log)文件中,可用于调试、性能分析以及对接外部日志采集平台(如 OpenTelemetry、Filebeat、Fluentd 等)。

该功能支持 mount、gateway 和 webdav 命令。设置 --access-log 后,所有文件系统操作都会被记录到指定文件中。生成的日志可以用 juicefs profile 命令进行分析。

自 5.4.5 起,轮转参数更名为 --log-rotate-size 和 --log-rotate-files(原参数名 --access-log-size 和 --access-log-files 仍作为别名兼容),并且同时控制 juicefs.log 的自动轮转,详见客户端日志轮转。

参数说明​

参数说明
--access-log=PATH指定访问日志文件的路径。设置后,JuiceFS 会将所有文件系统操作记录到该文件中;不设置则不持久化访问日志。日志文件以 0666 权限创建,所有用户均可读写。
--log-rotate-size=SIZE 新增自 v5.4.5(别名 --access-log-size,默认 300M)单个日志文件的轮转大小阈值,当前日志文件达到该大小时触发轮转。支持 K/M/G/T 等大小后缀(大小写均可),例如 2G 表示 2 GiB。该参数同时控制 juicefs.log 的轮转大小,设为 0 可关闭 juicefs.log 的自动轮转。建议在高 I/O 场景下适当调大,以降低轮转频率、减少对外部日志采集的影响。
--log-rotate-files=N 新增自 v5.4.5(别名 --access-log-files,默认 7)保留的轮转日志文件数量,最小值为 2(设为 1 时实际按 2 处理)。始终保留最近 2 个轮转文件为未压缩的纯文本,确保外部日志采集工具有足够的时间窗口完成读取;编号大于 2 的历史文件会被 gzip 压缩以节省磁盘空间。超过 N 个文件后,最老的文件会被删除。该参数同时控制 juicefs.log 保留的轮转文件数量。
备注

这组轮转参数由 mount、gateway 和 webdav 命令共享,同时控制 juicefs.log 的自动轮转。详见客户端日志轮转。

用法示例​

juicefs mount test-volume /mnt/jfs \
--access-log /var/log/juicefs-access.log \
--log-rotate-size 2G \
--log-rotate-files 10

日志轮转机制​

以 --log-rotate-files 5 为例,轮转流程如下:

  1. 活跃日志 juicefs-access.log 达到 --log-rotate-size 阈值,触发轮转。

  2. 将 juicefs-access.log 重命名为 juicefs-access.log.1。

  3. 所有已有文件编号 +1,同时将编号大于 2 的文件压缩:

    • juicefs-access.log.1 → juicefs-access.log.2(保持未压缩)
    • juicefs-access.log.2 → 压缩为 juicefs-access.log.3.gz
    • juicefs-access.log.3.gz → juicefs-access.log.4.gz
    • juicefs-access.log.4.gz → juicefs-access.log.5.gz
    • juicefs-access.log.5.gz → 删除(超出保留数量)
  4. 创建新的 juicefs-access.log 继续写入。

为避免日志占满磁盘,如果轮转时无法重命名日志文件(例如被外部工具占用),且文件大小超过 N × --log-rotate-size(N 为保留数量),客户端会将当前日志文件截断为 0 字节,文件内容全部丢弃。

最终磁盘上的文件结构:

juicefs-access.log           # 当前活跃日志
juicefs-access.log.1 # 最近一次轮转,未压缩
juicefs-access.log.2 # 前一次轮转,未压缩
juicefs-access.log.3.gz # 更早的历史日志,已压缩
juicefs-access.log.4.gz
juicefs-access.log.5.gz

为什么保留 2 个未压缩文件?​

轮转时旧日志会被 gzip 压缩并最终删除。如果使用 OpenTelemetry、Filebeat 等外部日志采集工具通过 glob pattern(如 juicefs-access.log*)追踪文件,采集工具可能来不及在文件被压缩/删除前完成读取,导致部分日志丢失。

保留最近 2 个未压缩文件后:

  • 文件名可预测(juicefs-access.log.1、juicefs-access.log.2),采集工具可通过 glob pattern 稳定追踪。
  • 采集工具有充足的时间窗口完成数据采集。
  • 不会因轮转过快导致老日志「采了就丢」。

磁盘空间估算​

假设 --log-rotate-size 2G、--log-rotate-files 5:

文件大小
juicefs-access.log.1约 2 GiB(未压缩)
juicefs-access.log.2约 2 GiB(未压缩)
juicefs-access.log.3.gz ~ juicefs-access.log.5.gz约 0.5~1 GiB(压缩后,纯文本压缩率极高)
合计约 5 GiB

对接外部日志采集工具​

OpenTelemetry Collector​

receivers:
filelog:
include:
- /var/log/juicefs-access.log
- /var/log/juicefs-access.log.?
exclude:
- /var/log/juicefs-access.log.*.gz
start_at: beginning
service:
pipelines:
logs:
receivers: [filelog]
exporters: [your_exporter]

Filebeat​

filebeat.inputs:
- type: filestream
paths:
- /var/log/juicefs-access.log
- /var/log/juicefs-access.log.?
exclude_files: ['.gz$']

注意事项​

  • 采集端的 glob pattern 应精准匹配未压缩文件(如 juicefs-access.log.?),避免读取 .gz 压缩文件产生乱码。
  • OpenTelemetry filelog receiver 通过 inode 追踪文件,轮转后会自动识别新 inode,但建议设置 start_at: beginning 确保首次启动不遗漏历史数据。
  • 跨文件的时序保证需依赖日志条目本身的时间戳,而非文件级别的读取顺序。
  • 采集工具在文件一段时间没有新写入后会停止跟踪该文件(具体超时取决于采集工具),因此只有当前活跃的 juicefs-access.log 会被持续读取。