持久化访问日志
自 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 为例,轮转流程如下:
-
活跃日志
juicefs-access.log达到--log-rotate-size阈值,触发轮转。 -
将
juicefs-access.log重命名为juicefs-access.log.1。 -
所有已有文件编号 +1,同时将编号大于 2 的文件压缩:
juicefs-access.log.1→juicefs-access.log.2(保持未压缩)juicefs-access.log.2→ 压缩为juicefs-access.log.3.gzjuicefs-access.log.3.gz→juicefs-access.log.4.gzjuicefs-access.log.4.gz→juicefs-access.log.5.gzjuicefs-access.log.5.gz→ 删除(超出保留数量)
-
创建新的
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会被持续读取。


