Repository files navigation

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

The Logfile Navigator is a log file viewer for the terminal. Given aset 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 thelnav TUI, you can:

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

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

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

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

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

$ ssh playground@demo.lnav.org

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

$ ssh tutorial1@demo.lnav.org

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

$brew install lnav

Simply pointlnav at the files or directories you want tomonitor, it will figure out the rest:

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

Thelnav TUI will pop up right away and begin indexing thefiles. Progress is displayed in the "Files" panel at thebottom. Once the indexing has finished, the LOG view will displaythe log messages that were recognized¹. You can then use theusual hotkeys to move around the view (arrow keys orj/k/h/l to move down/up/left/right).

See theUsage sectionof the online documentation for more information.

On systems runningsystemd-journald, you can uselnav as the pager:

$ journalctl | lnav

or in follow mode:

$ journalctl -f | lnav

Sincejournalctl's default output format omits the year, if you areviewing logs which span multiple years you will need to change theoutput format to include the year, otherwiselnav gets confused:

$ journalctl -o short-iso | lnav

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

$ journalctl -o json | lnav

In case some MESSAGE fields contain special characters such asANSI color codes which are considered as unprintable by journalctl,specifyingjournalctl's-a option might be preferable in orderto 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 tothe ones actually recognized bylnav 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 increasedefficiency you may want to limit the number of log lines fed intolnav, e.g. viajournalctl's-n or--since=... options.

In case of a persistent journal, you may want to limit the numberof log lines fed intolnav viajournalctl's-b option.

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

• support@lnav.org
• Discord
• Google Groups

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

• Become a Sponsor on GitHub

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.
• ncurses - The ncurses text UI library.
• 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.

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

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.