journalctl cursor 怎样断点读取日志

我在需要重复拉取 systemd 日志时，最容易踩的坑不是过滤条件，而是把“上次看到哪里”误当成时间。journalctl 的 cursor 是日志条目的位置标识：--cursor 会从这个位置开始，--after-cursor 才是从它后面开始；如果任务只是持续读取，优先使用 --cursor-file 让 journalctl 负责保存最后一个游标。

官方文档：https://www.freedesktop.org/software/systemd/man/latest/journalctl.html

下面的重点是“断点”语义，不把 cursor 拆成时间戳，也不把它和 --since 混成同一种筛选条件。

三种 cursor 参数到底差在哪里

可以先记住一个判断：--show-cursor 负责把游标显示出来，--cursor 和 --after-cursor 负责把游标作为读取起点。官方把游标定义为不透明文本，它唯一描述某条 journal entry 的位置，应用层不需要解析其中的字段。

因此，手动保存游标时通常是“第一次读取加 --show-cursor，下一次读取加 --after-cursor”。如果把第二次调用写成 --cursor，断点条目可能再次出现，这在增量同步或巡检脚本中会造成重复处理。

用 cursor-file 保存连续读取断点

只要任务是反复调用同一组查询，--cursor-file=FILE 更省心。文件存在时，journalctl 使用其中的游标从后面继续；文件不存在时，仍按其他参数读取；命令结束时再把最后一条条目的游标写回文件。

# 固定服务过滤条件，让每次调用处理同一类日志
journalctl --unit=my-service.service \
  --cursor-file=/var/lib/my-service/journal.cursor \
  --output=short-iso --no-pager

# 让脚本能区分读取失败与正常完成，并保留断点文件
status=$?
if [ "$status" -ne 0 ]; then
  # 非零退出时不要把外部状态误认为新的成功断点
  exit "$status"
fi

这个写法有两个实际边界。第一，过滤条件应保持稳定；如果上一次按服务过滤、下一次突然改成全局日志，断点含义就不再对应同一批数据。第二，游标文件应放在任务有权限读写且能持久保存的位置，不能因为临时目录清空而意外回到初始读取范围。

需要自己管理游标时怎么写

有些程序会把断点放进数据库、队列状态或任务元数据，这时可以手动传递 cursor。先用 --show-cursor 获取输出末尾的游标，再把完整字符串原样交给下一次 --after-cursor。

# 第一次读取时把最后游标打印在输出末尾
journalctl --unit=my-service.service --lines=100 \
  --show-cursor --no-pager

# CURSOR_VALUE 应由程序原样保存，不要截断或改写
journalctl --unit=my-service.service \
  --after-cursor="$CURSOR_VALUE" --no-pager

不要只保存显示出来的时间，也不要按分号、等号等字符拆解游标。时间只能帮助人定位大概范围，不能替代 journal 的位置标识；如果必须把断点跨主机传递，也应把它当作完整文本保存。

几个容易误判的边界

• --cursor 不是“严格下一条”。需要避免重复处理时使用 --after-cursor 或 --cursor-file。
• cursor 不是时间过滤器。--since 和 --until 仍然是时间范围条件，不能用来替代精确断点。
• 游标依赖 journal 中的条目。日志轮换、清理或保留策略变化后，旧断点可能不再适合当前数据集；这时应由任务决定如何重新建立起点，而不是猜测游标格式。
• 没有新条目时不要伪造新游标。脚本应保留上一次成功读取的状态，并把退出码和业务处理结果分开记录。

相关问题

journalctl 的 cursor 能当 Unix 时间戳吗？

不能。它是描述条目位置的不透明文本；需要按时间筛选时使用 --since 或 --until。

为什么第二次读取还会出现上一条日志？

常见原因是把游标传给了 --cursor。改用 --after-cursor，或直接让 --cursor-file 管理断点。

手动保存游标和 cursor-file 选哪个？

单机、固定查询任务优先用 --cursor-file；需要把状态写入业务存储或和任务记录绑定时，再手动保存完整 cursor。

简要说，journalctl 断点读取的关键不是记住一个时间，而是稳定保存上次成功处理的 journal cursor：想排除已读条目就用 --after-cursor，想减少状态管理就用 --cursor-file。