企业官网建设流程全解析

• 开发工具
• 日志分析
• CLI

本文基于 lnav（Log file navigator）仓库中的功能变更说明（docs/_posts/2018-05-17-tags-and-comments.md）撰写，该功能自 v0.8.4 起可用。文章结合当前仓库源码（src/cmds.metadata.cc、src/bookmarks.hh、src/log_vtab_impl.cc）展开，帮助你理解并熟练使用 lnav 的日志标注能力。

导读

排查日志时，你常常会想给某条关键消息“做个记号”或“写点备注”——记录它为什么可疑、对应哪个 Bug、需要谁来复审。lnav 为此提供了:comment与:tag两条命令：它们把注释和标签直接挂到日志视图中的某条消息上，并随会话持久化保存，重新打开文件即可自动恢复。本文将从命令用法、会话存储原理、搜索方式、SQL 查询列四个层面完整讲解这一功能，并给出可直接复制的操作示例。

功能总览：给日志消息“做批注”

lnav 的标注功能让用户可以把个人思考附加到感兴趣的日志消息上：

• :comment：为日志视图中顶部（当前聚焦）的日志消息添加一条注释；
• :tag：为日志视图中顶部消息添加一个或多个标签（tag）；
• 注释与标签保存在session（会话）中，当同一文件被重新打开时会自动恢复；
• 这些标注可以被常规搜索检索到；
• 在日志表（log tables）中可以通过log_tags与log_comment两列访问。

从源码结构看，这套能力属于“元数据（metadata）”命令家族。当前仓库中与之配套的命令还包括:clear-comment、:untag、:delete-tags、:partition-name、:clear-partition以及较新加入的:annotate，它们统一注册在 src/cmds.metadata.cc 的METADATA_COMMANDS表中，并带有metadata标签，便于在命令补全中归类。

:comment —— 为消息写下你的想法

基本用法

在日志视图中，将光标移到目标消息（即视图顶部的聚焦行），然后执行：

:comment 这是问题开始的地方

• 命令会为当前聚焦行添加注释，注释内容会紧贴在其对应的日志消息下方显示；
• 注释文本支持Markdown 指令，可用于样式化与添加链接（如**加粗**、链接等）；
• 命令执行成功后返回提示info: comment added to line。

从 src/cmds.metadata.cc 的实现可以看到，命令执行时会先对文本做反引号解包（unquote_content），然后将注释写入该行的元数据line_meta.bm_comment，同时把该行标记为BM_META元数据书签（用于后续跳转），并触发视图刷新。若当前视图不是 LOG 视图，命令会报错：

The :comment command only works in the log view

另外，在非执行模式（dry-run）下，:comment还会用 Markdown 解析器（md4cpp）渲染注释文本，并在预览视图中展示渲染效果，方便你确认格式无误。

编辑已有注释

再次对同一行执行:comment，可以覆盖/更新原有的注释。执行:comment时，命令补全（prompt）会自动带回该行已有的注释文本，方便你在此基础上修改——这一行为由com_comment_prompt（src/cmds.metadata.cc）实现，它会读取当前行bm_comment并回填到命令行。

清除注释

:clear-comment

清除聚焦行上的注释。若该行不再拥有任何注释/标签（笔记类元数据为空），BM_META标记会被移除；若整行元数据清空，则连元数据记录一并删除（见 src/cmds.metadata.cc）。

:tag —— 用标签给消息分类

基本用法

:tag #BUG123 #needs-review

• 一次可添加一个或多个标签，标签之间用空格分隔；
• 标签可以带#前缀，也可以不带——实现中若参数不以#开头会自动补上（见 src/cmds.metadata.cc）；
• 所有添加过的标签会记入全局的已知标签集合bookmark_metadata::KNOWN_TAGS（定义于 src/bookmarks.hh），供后续命令补全与校验使用；
• 执行成功返回提示info: tag(s) added to line。

移除与批量删除

• :untag只影响当前聚焦行，移除后若该行不再有其他注释/标签，BM_META标记会被清除；
• :delete-tags会遍历所有被标记的行逐一移除标签，同时从KNOWN_TAGS中删除该标签；若目标是未知标签会报错Unknown tag -- <tag>（见 src/cmds.metadata.cc）。

标签的数据结构

在源码中，每行的标签以std::vector<tag_entry> bm_tags形式存放在bookmark_metadata结构里（src/bookmarks.hh），并提供add_tag/remove_tag方法。格式解析器也可能向行元数据写入标签（例如某些日志格式自动提取的标签），其来源通过meta_source区分，避免与用户手打标签混淆。

持久化：标注随会话自动保存与恢复

这是本功能最实用的特性之一：注释和标签保存在 session 中。当你在 lnav 中标注了某条消息并退出后，这些标注会写入会话数据；再次打开同一日志文件时，lnav 会自动恢复这些标注，无需重新添加。

• 会话文件存放在 lnav 的数据目录（默认~/.lnav/下的会话文件）中；
• 恢复过程由会话加载逻辑（src/session_data.cc）在文件打开时重建各行的bookmark_metadata，包括注释、标签等；
• 这一机制让标注成为“长期备忘”，非常适合反复跟踪的日志文件或跨天排查的场景。

检索标注：普通搜索即可命中

注释和标签都被纳入 lnav 的文本搜索范围。在日志视图中按下/打开普通搜索提示（search prompt），输入注释文字或标签名（如#BUG123），即可在全部消息中定位到被标注的行：

• 搜索不仅匹配日志正文，也匹配行元数据中的注释与标签；
• 所有带注释/标签的行还会被标记为BM_META书签，可在 lnav 中通过书签跳转（默认M键切换元数据书签视图）快速遍历。

在 SQL 中访问：log_tags 与 log_comment 列

标注数据不只停留在界面层，lnav 把每一条日志消息都暴露为 SQLite 虚拟表（log tables）中的一行，其中包含两列专门用于标注访问：

这两列的定义可以在 src/log_vtab_impl.cc 中看到：

log_comment TEXT, -- The comment for this message log_tags TEXT, -- A JSON list of tags for this message

你可以直接在 lnav 的 SQL 提示（:sql或;前缀）中查询。例如，查找所有带注释的消息：

SELECT log_line, log_time, log_comment FROM <log_table> WHERE log_comment IS NOT NULL;

查找被打上#BUG123标签的消息（log_tags为 JSON 数组，可用 JSON 函数处理）：

SELECT log_line, log_msg, log_tags FROM <log_table> WHERE log_tags LIKE '%BUG123%';

其中<log_table>是当前日志文件对应的表名（通常是文件名去扩展名后的标识符，可通过log_format等列进一步筛选）。此外，log_vtab_impl的插入逻辑（src/log_vtab_impl.cc）表明，向这些列写入值也会反向更新该行的bm_comment与bm_tags，也就是说你甚至可以通过 SQL 更新来批量设置注释和标签——例如用一条UPDATE语句给多行添加同一个标签。

更进一步的元数据命令：partition-name 与 annotate

在同一个命令家族中，还有两个命令与标注功能互补，值得一提：

• :partition-name <name>：将聚焦行标记为名为<name>的新分区的起点，用于给日志流分段；:clear-partition清除聚焦行所在的分区名；
• :annotate：对聚焦消息运行配置中定义的“注解（annotation）”条件与处理器，自动附加分析结果。

其中:annotate是较新加入的能力，核心实现位于 src/log.annotate.cc：它会逐一评估配置的注解条件（SQL 表达式），对满足条件的消息调用外部脚本或内联命令作为 handler，并把输出以 Markdown 形式附着到消息上（见 src/log.annotate.hh 中applicable/apply两个函数）。这可以视为:comment的“自动化版本”——由配置驱动、按条件批量生成批注。

总结

注释与标签让 lnav 从“只看日志”升级为“可长期批注的日志工作台”。结合会话持久化、文本搜索与 SQL 查询三重视角，无论是日常排障、审计回溯还是团队协作交接，都能把你在日志中发现的线索固化成可复用的信息资产。

如需深入了解相关命令的完整帮助文本，可在 lnav 中输入:help comment、:help tag查看内置说明；实现细节可继续阅读 src/cmds.metadata.cc、src/bookmarks.hh 与 src/log_vtab_impl.cc。

• 开发工具
• 日志分析
• CLI