Scripts

Commands and SQL queries can be combined into scripts to automate tasks, like finding log messages or creating reports. For example, lnav includes a partition-by-boot script that partitions the log view based on boot messages from the Linux kernel. A script can have a mix of SQL and lnav commands, as well as include other scripts. The type of statement to execute is determined by the leading character on a line: a semi-colon begins a SQL statement; a colon starts an lnav command; and a pipe | denotes another script to be executed. Lines beginning with a hash are treated as comments. Script files should be named with a .lnav extension.

Scripts can be located anywhere in the file system and executed by giving their full path in the | prompt. Or, scripts can be installed in format directories so they can be called by just their base name. You can also create .sql files that contain SQL statements to be executed on startup. A good use for SQL files is creating a helper TABLE or VIEW to be used for other queries.

The following variables are defined in a script:

#

The number of arguments passed to the script.

__all__

A string containing all the arguments joined by a single space.

0

The path to the script being executed.

1-N

The arguments passed to the script.

LNAV_HOME_DIR

The path to the directory where the user’s lnav configuration is stored.

LNAV_WORK_DIR

The path to the directory where lnav caches files, like archives that have been unpacked or piper captures.

Remember that you need to use the :eval command when referencing variables in most lnav commands. Scripts can provide help text to be displayed during interactive usage by adding the following tags in a comment header:

@synopsis:

The synopsis should contain the name of the script and any parameters to be passed. For example:

# @synopsis: hello-world <name1> [<name2> ... <nameN>]

@description:

A one-line description of what the script does. For example:

# @description: Say hello to the given names.

@output-format:

The MIME type of the output generated by the script. When set to text/markdown the :write-table-to will generate Markdown tables.

Tip

The :eval command can be used to do variable substitution for commands that do not natively support it. For example, to substitute the variable, pattern, in a :filter-out command:

:eval :filter-out ${pattern}

VSCode Extension

The lnav VSCode Extension can be installed to add syntax highlighting to lnav scripts.

Builtin Scripts

The following scripts are built into lnav.

find-msg

This script can help in finding log messages that are related to the focused message. lnav already provides hotkeys for finding messages based on common fields, but this script can be used for arbitrary fields.

find-msg source

find-chained-msg

This script is similar to find-msg, except instead of matching a single field in the focused and next/previous message, the matched value can be in separate fields.

find-chained-msg source

report-access-log

This script generates a report from the access_log table that is similar to the output of the goaccess tool.

report-access-log souurce