lnav Cookbook 实战指南:日志高亮、分区标注、SQL 分析与报告生成

原创2026-09-23 23:13:331,427 阅读
文章标签:日志分析CLI开发工具

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_tags JSON 数组中,实现"累加标签"而不是覆盖。
  • 与上一个脚本一致,末尾用 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)都可以直接下载使用,并根据自身日志格式、字段名与业务口径稍作调整后投入日常运维。

登录后查看全文
lnav