docs/source/scripts.rst
.. _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
:file: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 :code:| denotes
another script to be executed. Lines beginning with a hash are treated as
comments. Script files should be named with a :file:.lnav extension.
Scripts can be located anywhere in the file system and executed by giving
their full path in the :kbd:| prompt. Or, scripts can be
:ref:installed<installing_format_files> in format directories so they can be
called by just their base name. You can also create :file:.sql files that
contain SQL statements to be executed on startup. A good use for SQL files is
creating a helper :code:TABLE or :code:VIEW to be used for other queries.
The following variables are defined in a script:
.. envvar:: #
The number of arguments passed to the script.
.. envvar:: all
A string containing all the arguments joined by a single space.
.. envvar:: 0
The path to the script being executed.
.. envvar:: 1-N
The arguments passed to the script.
.. envvar:: LNAV_HOME_DIR
The path to the directory where the user's lnav configuration is stored.
.. envvar:: 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 :ref::eval<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 :code:text/markdown the :ref::write-table-to<write_table_to>
will generate Markdown tables.
.. tip::
The :ref::eval<eval> command can be used to do variable substitution for
commands that do not natively support it. For example, to substitute the
variable, :code:pattern, in a :ref::filter-out<filter_out> command:
.. code-block:: lnav
:eval :filter-out ${pattern}
The lnav VSCode Extension <https://marketplace.visualstudio.com/items?itemName=lnav.lnav>_
can be installed to add syntax highlighting to lnav 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 <https://github.com/tstack/lnav/blob/master/src/scripts/find-msg.lnav>_
find-chained-msg ^^^^^^^^^^^^^^^^
This script is similar to :code: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 <https://github.com/tstack/lnav/blob/master/src/scripts/find-chained-msg.lnav>_
report-access-log ^^^^^^^^^^^^^^^^^
This script generates a report from the :code:access_log table that is
similar to the output of the goaccess <https://goaccess.io>_ tool.
report-access-log souurce <https://github.com/tstack/lnav/blob/master/src/scripts/report-access-log.lnav>_