lnav Cookbook 实战指南:日志高亮、分区标注、SQL 分析与报告生成
lnav Cookbook 实战指南:日志高亮、分区标注、SQL 分析与报告生成
本指南完整翻译并深入展开 lnav 官方 Cookbook 中的全部实战配方,覆盖四个方面:用格式补丁文件为 Web 访问日志字段自定义高亮、用分区与标签组织杂乱日志、借助内建 SQL 扩展完成 IP 统计与字段区间过滤,以及用 .lnav 脚本生成结构化报告和 Runbook。文中每个配方都配以仓库内的完整可运行脚本与对应源码实现(含文件路径与行号),读完后你可以直接复制改造,用于自己的日常日志排查与分析流水线。
自定义 Web 访问日志高亮
lnav 允许通过"格式补丁文件"为某个日志格式增加高亮规则:只要编写一个 JSON 文件,声明要修补的格式名与字段,并把高亮规则挂到该字段对象下的 highlights 键中,lnav 就会在渲染对应字段时按规则匹配上色。
仓库中的 example-scripts/access_log_highlights.json 是一个完整的示例,它修补内置的 access_log 格式,为 sc_status(HTTP 状态码)字段添加三种状态高亮:
{
"$schema": "https://lnav.org/schemas/format-v1.schema.json",
"access_log": {
"value": {
"sc_status": {
"highlights": {
"ok": {
"pattern": "^200$",
"color": "green"
},
"forbidden": {
"pattern": "^403$",
"color": "#af0000"
},
"redirect": {
"pattern": "^(?:301|302)$",
"color": "#00afff"
}
}
}
}
}
}
要点说明:
- 顶层键是格式名:
access_log指明要修补的内置格式,文件不会替换整个格式定义,而是与之合并。 value/<字段名>下挂高亮:sc_status是 access_log 格式中的状态码字段,高亮只作用于该字段的取值。- 每条高亮规则包含
pattern(PCRE 正则)与color(颜色)。颜色既可以使用命名色(如green),也可以使用十六进制 RGB(如#af0000深红、#00afff亮蓝)。lnav 仓库内置了一份 CSS 颜色名表 src/css-color-names.json,命名色即按该表解析。
安装方法:把文件保存到 lnav 的用户格式目录下的 formats/ 子目录(例如命名为 formats/access_log.json)。从源码看,加载器会按 formats/*/*.json 的 glob 模式扫描格式定义文件(见 src/log_format_loader.cc),并在解析过程中按需合并;例如 value_def_provider 在遇到当前格式中尚未定义的值对象时,会动态创建 value_def 并注册进该格式(见 src/log_format_loader.cc),这正是补丁文件可以"叠加"字段与高亮规则而不破坏原格式的底层机制。
高亮规则最终如何生效?在 src/log_format.cc 中可以看到完整的编译链路:每条高亮的 pattern 会被编译为 PCRE2 代码(若留空则默认使用 .*),并与字段名、样式属性(attrs)绑定,支持 nestable(可嵌套)选项,还支持通过 captures 为模式中的命名捕获组单独指定样式。这意味着高亮不仅限于"整个字段变色",还可以精细到字段值内部的子串。
标注日志:分区与标签
"标注"是 lnav 帮助你整理日志的两类手段:分区(partition) 把日志视图切分成逻辑段落,标签(tag) 给感兴趣的消息打上标记,便于后续筛选定位。
为 Linux 多次启动创建分区
当一批日志横跨多个逻辑阶段(例如一次内核启动、一次部署、一次故障周期)时,可以用 lnav 的分区功能跟踪当前所在段落。分区名会显示在顶部状态栏中当前时间的旁边。
仓库中的 src/scripts/partition-by-boot.lnav 演示了如何基于 Linux 内核启动消息为每一"次启动"建立分区:
;
UPDATE syslog_log
SET log_part = 'Boot: ' || log_time
WHERE log_text LIKE '%kernel:%Linux version%';
;SELECT 'Created ' || changes() || ' partitions(s)';
脚本逻辑非常直观:
- 第一条语句用
UPDATE直接改写syslog_log表的log_part列:凡是log_text匹配%kernel:%Linux version%的消息(即内核打印版本号、标志一次启动开始的消息),就把它自身的时间戳写成分区名,形如Boot: 2026-09-23 03:07:43。 - 第二条语句借助 SQLite 的
changes()函数回显本次更新影响的记录数,方便确认脚本是否按预期执行。
除了用 SQL 批量设置,你还可以在交互界面中手动管理分区::partition-name 为当前聚焦行设置分区名,:clear-partition 清除该行所在分区(命令参考见 src/internals/cmd-ref.rst)。与之同族的标注命令还有 :annotate(加注解)与 :comment(加评论),它们与分区、标签一起构成了 lnav 的完整"日志标注"体系(见 src/internals/cmd-ref.rst)。
标记 SSH 日志消息
标签有两种添加方式:交互式地用 :tag 命令给当前消息打标签,或在脚本中用 SQL 批量打标签。仓库中的 example-scripts/tag-ssh-msgs.lnav 演示了后者——扫描所有日志中疑似 SSH 暴力破解的消息并自动加标签:
;
UPDATE all_logs
SET log_tags = json_concat(log_tags, '#ssh.invalid-user')
WHERE log_text LIKE '%Invalid user from%';
;SELECT 'Tagged ' || changes() || ' messages';
关键点:
- 目标是
all_logs这个"全量日志"虚拟表,因此不需要关心当前打开的是哪种格式的日志。 json_concat是 lnav 通过 SQL 扩展注册的 JSON 处理函数(实现位于 src/json-extension-functions.cc),这里把#ssh.invalid-user追加到该行已有的log_tagsJSON 数组中,实现"累加标签"而不是覆盖。- 与上一个脚本一致,末尾用
changes()报告处理条数。
用 SQL 扩展做日志分析
lnav 的核心分析能力来自内建的 SQL 扩展(sql-ext):所有已识别的日志都被建模成可查询的虚拟表(如 access_log、syslog_log、all_logs),可以直接写 SQL。Cookbook 特别提醒:当单个查询过大、或需要依次执行多条语句时,把它们写进一个 .lnav 脚本,再在 lnav 中使用 | 命令提示符执行,会比在单行输入框里反复粘贴方便得多。
统计 Web 访问日志中的客户端 IP
统计每个客户端 IP 的出现次数,并按次数从高到低排序:
;SELECT c_ip, count(*) as hits FROM access_log GROUP BY c_ip ORDER BY hits DESC
access_log 表的列名沿用 Apache/nginx 通用日志字段命名(c_ip 即 client IP),可以直接在查询中引用。统计结果默认呈现在 DB 视图中。
只显示数值字段处于某个区间的行
:filter-expr 命令允许用 SQL 表达式对日志行做过滤。下面的命令把 Web 访问日志过滤到"传输给客户端的字节数在 10,000 到 40,000 之间"的行:
:filter-expr :sc_bytes BETWEEN 10000 AND 40000
注意字段前的 : 前缀是 lnav 的字段引用语法(在过滤表达式中引用日志字段需要加冒号)。:filter-expr 支持任意布尔表达式组合,例如参考 src/internals/cmd-ref.rst 中的示例:
:filter-expr :log_procname = 'syslogd'
:filter-expr :log_body REGEXP 'id\d+' AND :log_body REGEXP 'foo'
即可以用 =、REGEXP、AND/OR、BETWEEN 等 SQL 操作符自由组合过滤条件。
用脚本生成报告
报告的本质是一个 .lnav 脚本:先用 SQL 查询统计数据,再通过一组"输出命令"把结果格式化成文档。最简单的脚本只需执行一条 SQL 查询并让结果显示在 DB 视图里;更复杂的报告则组合使用:
:echo:输出纯文本(若已用:redirect-to重定向,则写入目标文件而不是屏幕);- SQL 查询后紧跟"写入"命令,如
:write-table-to,把查询结果以表格形式输出。
仓库中的 example-scripts/report-demo.lnav 是一个完整可运行的代表性报告脚本,这里逐段拆解:
# @synopsis: report-demo [<output-path>]
# @description: Generate a report for requests in access_log files
脚本头部的 @synopsis / @description 注释用于在 lnav 的脚本菜单中展示说明,方便从 UI 直接发起执行。
;SELECT CASE
WHEN $1 IS NULL THEN '-'
ELSE $1
END AS out_path
:redirect-to $out_path
$1 是脚本的第一个命令行参数,即输出文件路径;缺省为 -,表示输出到 stdout。out_path 变量随后被 :redirect-to 消费,把此后所有输出命令的结果重定向到该文件。- 的语义(回到标准输出)与 :redirect-to 的实现一致:从 src/cmds.io.cc 可以看到,无参数调用会清除重定向,参数为 - 时同样清除(回到 stdout),参数为 /dev/clipboard 时输出到系统剪贴板,普通路径则直接以写模式打开文件;在安全模式(secure mode)下写文件会被拒绝。
;SELECT printf('\n%d total requests', count(1)) AS msg FROM access_log
:echo $msg
第一条查询算出总请求数并格式化为消息字符串,随后 :echo $msg 打印它。:echo 支持变量替换与转义(见 src/internals/cmd-ref.rst),因此可以直接引用上一条 SQL 输出的变量。
接下来是报告的主体——"热门路径 Top 50 及周趋势":
;WITH top_paths AS MATERIALIZED (
SELECT
cs_uri_stem,
count(1) AS total_hits,
sum(sc_bytes) as bytes,
count(distinct c_ip) as visitors
FROM access_log
WHERE sc_status BETWEEN 200 AND 300
GROUP BY cs_uri_stem
ORDER BY total_hits DESC
LIMIT 50),
weekly_hits_with_gaps AS MATERIALIZED (
SELECT timeslice(log_time_msecs, '1w') AS week,
cs_uri_stem,
count(1) AS weekly_hits
FROM access_log
WHERE cs_uri_stem IN (SELECT cs_uri_stem FROM top_paths) AND
sc_status BETWEEN 200 AND 300
GROUP BY week, cs_uri_stem),
all_weeks AS (
SELECT week
FROM weekly_hits_with_gaps
GROUP BY week
ORDER BY week ASC),
weekly_hits AS (
SELECT all_weeks.week,
top_paths.cs_uri_stem,
ifnull(weekly_hits, 0) AS hits
FROM all_weeks
CROSS JOIN top_paths
LEFT JOIN weekly_hits_with_gaps
ON all_weeks.week = weekly_hits_with_gaps.week AND
top_paths.cs_uri_stem = weekly_hits_with_gaps.cs_uri_stem)
SELECT weekly_hits.cs_uri_stem AS Path,
printf('%,9d', total_hits) AS Hits,
printf('%,9d', visitors) AS Visitors,
printf('%9s', humanize_file_size(bytes)) as Amount,
sparkline(hits) AS Weeks
FROM weekly_hits
LEFT JOIN top_paths ON top_paths.cs_uri_stem = weekly_hits.cs_uri_stem
GROUP BY weekly_hits.cs_uri_stem
ORDER BY Hits DESC
LIMIT 10
:write-table-to -
这条查询展示了 lnav SQL 扩展的几大实用函数:
timeslice(log_time_msecs, '1w'):把毫秒时间戳按时间片分桶,'1w'表示按周聚合。该函数支持'5m'、'10m'等相对切片以及'before 4:30am'这类自然语言边界(示例见 src/time-extension-functions.cc)。这里用all_weeks × top_paths交叉连接并配合ifnull(..., 0)补零,保证没有流量的周也会出现在趋势里。printf('%,9d', ...):SQLite 内建函数,这里用千分位与定宽格式对齐数字列。humanize_file_size(bytes):把字节数格式化为易读的单位(KB/MB…),实现注册在 src/string-extension-functions.cc。sparkline(hits):lnav 特有的聚合函数,把一组数值渲染成迷你柱状图(微型 sparkline)。其实现位于 src/string-extension-functions.cc:聚合过程中记录所有值与最大值,最终逐值调用humanize::sparkline(value, max)生成每个柱条字符。
紧随其后的 :write-table-to - 把该查询结果以表格形式写到当前输出目标。从 src/cmds.io.cc 的实现看,write-table-to(以及兄弟命令 write-cols-to)在普通文本输出时会用 Unicode 制表符绘制 ┏━┳━┓┃ 样式的表格边框;而当输出格式被设为 Markdown 时,则自动改用 | 管道表格语法,方便直接贴进文档。
报告最后一段统计"失败请求":
:echo
:echo Failed Requests
:echo
;SELECT printf('%,9d', count(1)) AS Hits,
printf('%,9d', count(distinct c_ip)) AS Visitors,
sc_status AS Status,
cs_method AS Method,
group_concat(distinct cs_version) AS Versions,
cs_uri_stem AS Path,
replicate('|', (cast(count(1) AS REAL) / $total_requests) * 100.0) AS "% of Requests"
FROM access_log
WHERE sc_status >= 400
GROUP BY cs_method, cs_uri_stem
ORDER BY Hits DESC
LIMIT 10
:write-table-to -
这里用 :echo 输出空行与章节标题做分隔;group_concat(distinct ...) 汇总同一路径上出现的 HTTP 版本;replicate('|', n) 把数值按比例转换成竖线字符串,做出 ASCII 条形图(该函数注册于 src/extension-functions.cc),并以 $total_requests 变量计算占比。
执行方式:把上述脚本交给 lnav 执行即可(例如在 lnav 内用 | 提示符运行脚本文件,或从 Runbook 的 Actions 菜单触发),脚本会在启动时逐条执行其中的 SQL 与命令,最终生成一份包含概览、热门路径周趋势与失败请求 Top10 的完整报告。
用 Markdown 建立 Runbook
如果你积累了一组 .lnav 脚本,可以把它们组织成一份 Runbook:写一个 Markdown 文件,用相对链接指向各个 .lnav 脚本。在 lnav 中打开该 Markdown 后,点击指向 .lnav 文件的链接会弹出 "Actions" 菜单,其中包含 "Execute" 菜单项——点击即可直接启动对应脚本,实现"从文档一键执行分析流程"的运营手册效果。
配合脚本头部的 @synopsis 与 @description 注释(如上面 report-demo 脚本所示),每个脚本在菜单中都会显示清晰的用途说明,使 Runbook 既是一份可读的文档,又是一套可点击执行的操作台。
相关命令速查
以下命令与上文各配方直接相关,均可在 lnav 内置命令参考 src/internals/cmd-ref.rst 中查到完整说明:
| 命令 | 用途 | 参考位置 |
|---|---|---|
:filter-expr <expr> |
用 SQL 表达式过滤当前日志视图 | cmd-ref.rst |
:partition-name <name> |
为当前聚焦行设置分区名 | cmd-ref.rst |
:clear-partition |
清除当前行所在分区 | cmd-ref.rst |
:tag <tag> |
为当前消息交互式打标签 | cmd-ref.rst |
:echo <msg> |
输出文本,支持变量替换;重定向时写入目标文件 | cmd-ref.rst |
:redirect-to <path> |
重定向输出到文件/剪贴板/-(stdout) |
src/cmds.io.cc |
:write-table-to <path> |
把查询结果以表格形式写出 | src/cmds.io.cc |
:write-cols-to <path> |
同上,但只写列不写表头边框 | src/cmds.io.cc |
涉及 SQL 扩展函数(timeslice、sparkline、humanize_file_size、json_concat、replicate 等)的测试用例分别收录于 test/test_sql_time_func.sh、test/test_sql_str_func.sh 与 test/test_sql_json_func.sh,可作为验证函数行为与边界的参考。
以上即 lnav Cookbook 的全部配方及其源码级原理。每个示例脚本(access_log_highlights.json、partition-by-boot.lnav、tag-ssh-msgs.lnav、report-demo.lnav)都可以直接下载使用,并根据自身日志格式、字段名与业务口径稍作调整后投入日常运维。