lnav Documentation

File: README.md Copy Chapter

This is the source repository for lnav, visit https://lnav.org for a high level overview.

LNAV -- The Logfile Navigator

The Logfile Navigator is a log file viewer for the terminal. Given a
set of files/directories, lnav will:

• decompress as needed;
• detect their format;
• merge the files by time into a single view;
• tail the files, follow renames, find new files in directories;
• build an index of errors and warnings;
• pretty-print JSON-lines.

Then, in the lnav TUI, you can:

• jump quickly to the previous/next error (press e/E);
• search using regular expressions (press /);
• highlight text with a regular expression (:highlight command);
• filter messages using regular expressions or SQLite expressions;
• pretty-print structured text (press P);
• view a histogram of messages over time (press i);
• analyze messages using SQLite (press ;)

Screenshot Copy Chapter

The following screenshot shows a mix of syslog and web access log
files. Failed requests are shown in red. Identifiers, like IP
address and PIDs are semantically highlighted.

Why not **just** use `tail`/`grep`/`less`? Copy Chapter

The standard Unix utilities are great for processing raw text lines,
however, they do not understand log messages. Tail can watch
multiple files at a time, but it won't display messages in order by
time and you can't scroll backwards. Grep will only find matching
lines, but won't return a full multi-line log message. Less can only
display a single file at a time. Also, none of these basic tools
handle compressed files.

Try online before installing Copy Chapter

You can SSH into a demo node to play with lnav before installing.

The "playground" account starts lnav with a couple of log files as
an example:

$ ssh [email protected]

The "tutorial 1" account is an interactive tutorial that can teach
you the basics of operation:

$ ssh [email protected]

Installation Copy Chapter

Download a statically-linked binary for Linux/MacOS/Windows from the release page

Brew on MacOS Copy Section

$ brew install lnav

FreeBSD Copy Section

$ pkg install lnav

Usage Copy Chapter

Simply point lnav at the files or directories you want to
monitor, it will figure out the rest:

$ lnav /path/to/file1 /path/to/dir ...

The lnav TUI will pop up right away and begin indexing the
files. Progress is displayed in the "Files" panel at the
bottom. Once the indexing has finished, the LOG view will display
the log messages that were recognized[^1]. You can then use the
usual hotkeys to move around the view (arrow keys or
j/k/h/l to move down/up/left/right).

See the Usage section
of the online documentation for more information.

[^1]: Files that do not contain log messages can be seen in the
TEXT view (reachable by pressing t).

Usage with `systemd-journald` Copy Section

On systems running systemd-journald, you can use lnav as the pager:

$ journalctl | lnav

or in follow mode:

$ journalctl -f | lnav

Since journalctl's default output format omits the year, if you are
viewing logs which span multiple years you will need to change the
output format to include the year, otherwise lnav gets confused:

$ journalctl -o short-iso | lnav

It is also possible to use journalctl's json output format and lnav
will make use of additional fields such as PRIORITY and _SYSTEMD_UNIT:

$ journalctl -o json | lnav

In case some MESSAGE fields contain special characters such as
ANSI color codes which are considered as unprintable by journalctl,
specifying journalctl's -a option might be preferable in order
to output those messages still in a non-binary representation:

$ journalctl -a -o json | lnav

If using systemd v236 or newer, the output fields can be limited to
the ones actually recognized by lnav for increased efficiency:

$ journalctl -o json --output-fields=MESSAGE,PRIORITY,_PID,SYSLOG_IDENTIFIER,_SYSTEMD_UNIT | lnav

If your system has been running for a long time, for increased
efficiency you may want to limit the number of log lines fed into
lnav, e.g. via journalctl's -n or --since=... options.

In case of a persistent journal, you may want to limit the number
of log lines fed into lnav via journalctl's -b option.

Support Copy Chapter

Please file issues on this repository or use the discussions section.
The following alternatives are also available:

• [email protected]
• Discord
• Google Groups

Links Copy Chapter

• Main Site
• Documentation on Read the Docs
• Internal Architecture

Contributing Copy Chapter

• Become a Sponsor on GitHub

Building From Source Copy Section

Prerequisites

The following software packages are required to build lnav:

• gcc/clang - A C++14-compatible compiler.
• libpcre2 - The Perl Compatible Regular Expression v2 (PCRE2) library.
• sqlite - The SQLite database engine. Version 3.9.0 or higher is required.
• zlib - The zlib compression library.
• bz2 - The bzip2 compression library.
• libcurl - The cURL library for downloading files from URLs. Version 7.23.0 or higher is required.
• libarchive - The libarchive library for opening archive files, like zip/tgz.
• libunistring - The libunistring library for dealing with unicode.
• wireshark - The 'tshark' program is used to interpret pcap files.
• cargo/rust - The Rust language is used to build the PRQL compiler.

Build

Lnav follows the usual GNU style for configuring and installing software:

Run ./autogen.sh if compiling from a cloned repository.

$ ./configure
$ make
$ sudo make install

See Also Copy Chapter

Angle-grinder is a tool to slice and dice log files on the command-line.
If you're familiar with the SumoLogic query language, you might find this tool more comfortable to work with.

Code Signing Policy Copy Chapter

Free code signing provided by SignPath.io,
certificate by SignPath Foundation.

This program will not transfer any information to other networked systems
unless specifically requested by the user or the person installing or
operating it.

Acknowledgements Copy Chapter

Many thanks to:

• GitHub Sponsors
• Anthropic for including lnav in the Claude for Open Source Program

File: docs/_posts/2013-09-10-json-encoded-logs.md Copy Chapter

layout: post title: "Support for JSON-encoded logs in v0.6.1" date: 2013-09-10 00:00:00 excerpt: Turning JSON barf into something readable. Copy Chapter

Making logs easily digestible by machines is becoming a concern as tools like
elasticsearch become more popular. One of the popular strategies is to encode
the whole log message in JSON and then write that as a single line to a file.
For example:

{"time": "2013-09-04T23:55:09.274041Z", "level" : "INFO", "body" : "Hello, World!" }
{"time": "2013-09-04T23:56:00.285224Z", "level" : "ERROR", "body" : "Something terrible has happened!", "tb": "  foo.c:12\n bar.y:33" }

Unfortunately, what is good for a machine is not so great for a human. To try to
improve the situation, the latest release of lnav includes support for parsing
JSON log messages and transforming them on-the-fly. The display format is
specified in a log format configuration and can specify which fields should be
displayed on the main message line. Any unused fields that are found in the
message will be displayed below the main field so you don't miss anything.

The above log lines can be transformed using the following format configuration:

{
    "json_ex_log": {
        "title": "Example JSON Log",
        "description": "An example log format configuration for JSON logs",
        "json": true,
        "file-pattern": "test-log\\.json.*",
        "level-field": "level",
        "line-format": [
            {
                "field": "time"
            },
            " ",
            {
                "field": "body"
            }
        ]
    }
}

After copying this config to ~/.lnav/formats/test/format.json, the log messages
will look like this when viewed in lnav:

2013-09-04T23:55:09.274041Z Hello, World!
2013-09-04T23:56:00.285224Z Something terrible has happened!
  tb:   foo.c:12
  tb:   bar.y:33

File: docs/_posts/2013-09-13-four-years-on-github.md Copy Chapter

layout: post title: "Four years on GitHub" date: 2013-09-13 00:00:00 excerpt: Still going strong! Copy Chapter

The first commit
to the lnav repository was four years ago
today! I started working on lnav a couple of years before that, but this was
its first public appearance. I still use it every day and plan to keep things
going for years to come.

File: docs/_posts/2013-10-05-mini-review-in-linux-magazine.md Copy Chapter

layout: post title: "Mini review of lnav in Linux Magazine" date: 2013-10-05 00:00:00 Copy Chapter

The October issue of Linux Magazine
has a nice review of lnav v0.5.0, the author gave it four out of five stars!

File: docs/_posts/2013-10-06-competing-with-tail.md Copy Chapter

layout: post title: "Competing with 'tail -f'" date: 2013-09-10 00:00:00 excerpt: The standard utilities are tough competition. Copy Chapter

Probably the toughest competition for lnav is the standard Unix utilities like
tail, grep, less, and emacs/vim. It can be hard trying to convince people that
these built-in commands that they've used for forever can be improved upon. The
advanced features of lnav might even work against it since folks are expecting
to have to learn a bunch of stuff to see any benefits.

The reality is that there are quite a few "passive" features in lnav that can
provide value with no effort required by the user. For example, lnav can easily
replace 'tail -f', it's even shorter to type! Beyond the basic task of
displaying new lines appended to a log file, you also get to see log messages
from multiple files interleaved, the ability to scroll backwards, syntax
highlighting, live searching, and so on. These basic features do not have the
same "wow" factor as executing a SQL query over data automatically extracted
from a log file, but they're the features that get used 90% of the time.

Anyways, I think I'm gaining a new appreciation for marketing/sales...

File: docs/_posts/2013-11-01-mini-review-linux-user-magazine.md Copy Chapter

layout: post title: "Mini-review of lnav in Linux User Magazine" date: 2013-09-10 00:00:00 Copy Chapter

The german magazine, Linux User, has a
mini-review of lnav v0.6.0 in their
November issue!

File: docs/_posts/2014-02-22-changes-to-the-scrollbar.md Copy Chapter

layout: post title: "Changes To The Scrollbar" date: 2014-02-22 00:00:00 excerpt: Packing more information into the right scrollbar. Copy Chapter

I've made some changes to the scrollbar that is shown on the right side of the
display based on some feedback from users. The scroll area now has a single
vertical line extending from the top to the bottom. Previously, this area would
show log message characters and it wasn't very clear that the scroll bar
existed. The line is colored based whether there are errors or warnings in that
part of the log. The coloring should make it easier to see the distribution of
errors across the whole log. Similarly, there are notches added to the left and
right side of the line to show search hits and bookmarks, respectively. See the
following screenshot to get an idea of what it looks like:

These changes are currently only in the latest code from git. I'll be playing
with things a bit more before making a release.

File: docs/_posts/2014-11-11-lofi-mode.md Copy Chapter

layout: post title: Added "lo-fi" mode excerpt: An alternative way to copy displayed text. Copy Chapter

(This change is in v0.7.2+)

Copying text to the clipboard can be done by marking lines with the
bookmark hotkeys,
like m, and then pressing c. Commands that write to a file,
like :write-csv-to
accept /dev/clipboard as a way to write to the clipboard. However, if the
native clipboard isn't supported, or you're on an SSH connection, you can
now switch to "lo-fi" mode. In "lo-fi" mode, lnav drops out of the curses
display and prints the raw text to the terminal. You can switch to "lo-fi"
mode in a view by pressing CTRL-L. For commands, you can use a dash -
to switch to "lo-fi" and print to standard out.

File: docs/_posts/2015-04-11-pretty-print-view.md Copy Chapter

layout: post title: "Pretty-print view in v0.7.3" date: 2015-04-11 00:00:00 excerpt: Automatically reformat structured data with "SHIFT+P". Copy Chapter

I wanted to call out the pretty-print feature in the latest release of lnav.
This idea came from a coworker of Suresh who was having a hard time trying to
read some unformatted XML in a log. They wanted the XML pretty-printed and were
hoping that could be done by just piping the message to xmlpp or the like. So,
first we implemented the 'pipe-to' and 'pipe-line-to' commands that will let you
pipe log messages to a command and then display the result inside of lnav. That
worked well enough, but pretty-printing is such a frequent operation that having
to execute a command was kind of a pain. It would also be nice if it worked for
a variety of text, like JSON or Python data. The solution we came up with was to
leverage the existing code for parsing log messages to create a simple
pretty-printer that should work for most data formats. Another benefit is that
the log message does not have to be well-formed for the printer to work, any
leading or trailing garbage shouldn't confuse things.

As an example, here is a screenshot of the log message with the unformatted XML
text with word-wrapping turned on:

That's not very easy to read and it's hard to figure out the structure of the
message. Now, here is that same message after pressing SHIFT+P to switch to the
pretty-print view of lnav:

The XML text is indented nicely and the usual syntax highlighting is applied.
Also notice that lnav will automatically try to lookup the DNS name for IP
addresses. Overall, I think it's a major improvement over the raw view.

This is a pretty simple feature but I have found it quite useful in the couple
weeks that it has been implemented. It's so useful that I'm kicking myself for
not having thought of it before.

File: docs/_posts/2016-03-20-lnav-in-print.md Copy Chapter

layout: post title: "lnav in print" date: 2016-03-20 00:00:00 Copy Chapter

A review of lnav
is in Linux User & Developer magazine issue 162: