Introduction

A fancy, ncurses-based log file viewer.

The log file navigator, lnav, is an enhanced log file viewer that takes advantage of any semantic information that can be gleaned from the files being viewed, such as timestamps and log levels. Using this extra semantic information, lnav can do things like interleaving messages from different files, generate histograms of messages over time, and providing hotkeys for navigating through the file. It is hoped that these features will allow the user to quickly and efficiently zero in on problems.

Links

General

http://lnav.org/

Docs

http://lnav.readthedocs.io/en/latest/

Files and Directories

General Files and Directories

File or Directory	Description
`$HOME/.lnav/`	User-specific lnav directory
`$HOME/.lnav/view-info-<hash>.ts<epoch-timestamp>.ppid<PID>.json`	User-specific lnav session data. Position within the files being viewed. Active searches for each view. Any active log filters or highlights.

Configuration Files

File or Directory	Description
`/etc/lnav/formats`	System-wide lnav file format configuration for all users on the system.
`$HOME/.lnav/formats/`	User-specific lnav file format configuration.
`$HOME/.lnav/config.json`	User-specific lnav configuration file.

Getting Help

Manual pages:

user@host:~$ man lnav

Help file:

user@host:~$ lnav -H

or:

user@host:~$ zless /usr/share/doc/lnav/help.txt.gz

Install

To install lnav on Debian:

root@host:~$ apt-get update
root@host:~$ apt-get -y install lnav

Configuration

Check the configuration for validity:

user@host:~$ lnav -C

Usage

The following examples assume that the log files are at least readable to the user. If this is not the case, the lnav command has to be run under sudo or as the user root.

Command Line Parameters

Load the most recent syslog file (/var/log/syslog) for inspection:

user@host:~$ lnav -s

Load all the most recent known log files from the current working directory and from the directory /var/log/ for inspection. Watch the upper right display of the current file name as you scroll through the messages in order to determine from which particular log file the current line was extracted:

user@host:~$ lnav -a

Load older, already rotated log files for inspection as well:

user@host:~$ lnav -r

Load one or more specific log files for inspection:

user@host:~$ lnav /var/log/nginx/access.log /var/log/nginx/error.log

Load log files from a specific directory or matching a file name pattern for inspection:

user@host:~$ lnav /var/log/nginx/
user@host:~$ lnav /var/log/nginx/error*.log*

Automatically execute an internal lnav command upon execution. In this example jump to the line number 10 of the log file /var/log/syslog:

user@host:~$ lnav -c ':goto 10' /var/log/syslog

Automatically execute internal lnav commands stored in commands-file.txt upon execution:

user@host:~$ lnav -f commands-file.txt /var/log/syslog

Feed log data to lnav in a pipe in order to e.g. inspect log entries generated by systemd:

user@host:~$ journalctl | lnav

Display

The central main part of the display shows log lines sorted by time of day. The new log lines are continuously appended at the bottom of the display. If a colored display is available, the following colors will be used for highlighting:

Red: Errors
Yellow: Warnings
Turquoise: Hostname
Purple: Process name
Green: PID
Various colors to highlight different aspects, depending on the detected log line format.
Underline: Date line

The main part is also used to display other information additional (e.g. histograms and SQL results) to the pure display of log lines over time.

On the right side there is a scroll-bar indicating the current position in the file. Positions with warnings and errors will on the scroll-bar too be highlighted in the colors mentioned above.

Status lines are located above and below the central main part. The upper status line shows in this order from left to right:

the current date and time
the file the top-most line was gathered from
the detected log line format of the top-most line
the name of the current view mode

The lower status line shows in this order from left to right:

the line number of the top-most line within the current log file
the number of hits on a search action
the number of lines not displayed due to an active filter

The last of the display line takes user input for internal commands and search patterns. It is implemented with the readline library and thus understands the usual shortcuts configured there as well as tab-completion.

See the lnav Hotkey Reference for a complete list of keybindings.

Spatial Navigation

Keybinding	Description
`Space` or `Pgdn`	Move down a page.
`Backspace` or `b` or `Pgup`	Move up a page.
`Return` or `j` or `Downarrow`	Move down a line.
`k` or `Uparrow`	Move up a line.
`h` or `Leftarrow`	Move to the left half a page.
`H` or `Shift`+`Leftarrow`	Move to the left ten columns.
`l` or `Rightarrow`	Move to the right half a page.
`L` or `Shift`+`Rightarrow`	Move to the ight ten columns.
`g` or `Home`	Move to the top of the file.
`G` or `End`	Move to the end of the file. If the view is already at the end, it will move to the last line.
`e` or `E`	Move to the next/previous error.
`w` or `W`	Move to the next/previous warning.
`n` or `N`	Move to the next/previous search hit.
`>` or `<`	Move horizontally to the next/previous search hit.
`f` or `F`	Move to the next/previous file. In the log view, this moves to the next line from a different file. In the text view, this rotates the view to the next file.
`u` or `U`	Move forward/backward through any user bookmarks you have added using the `M` key. This hotkey will also jump to the start of any log partitions that have been created with the `partition-name` command.
`y` or `Y`	Move forward/backward through the log view based on the “log_line” column in the SQL result view.
`s` or `S`	Move to the next/previous “slow down” in the log message rate. A slow down is detected by measuring how quickly the message rate has changed over the previous several messages. For example, if one message is logged every second for five seconds and then the last message arrives five seconds later, the last message will be highlighted as a slow down.

Chronological Navigation

Keybinding	Description
`o` or `O`	Move forward/backward 60 minutes from the current position in the log file.
`d` or `D`	Move forward/backward 24 hours from the current position in the log file.
`1`-`6` or `Shift` `1`-`6`	Move to the next/previous n'th ten minute of the hour. For example, `4` would move to the first log line in the fortieth minute of the current hour in the log. And, `6` would move to the next hour boundary.
`0` or `Shift 0`	Move to the next/previous day boundary.
`r` or `R`	Forward/backward by the relative time that was last used with the goto command.

Bookmarks

Keybinding	Description
`m`	Mark/unmark the line at the top of the display. The line will be highlighted with reverse video to indicate that it is a user bookmark. You can use the `U` hotkey to iterate through marks you have added.
`M`	Mark/unmark all the lines between the top of the display and the last line marked/unmarked.
`J`	Mark/unmark the next line after the previously marked line.
`K`	Like `J` except it toggles the mark on the previous line.
`c`	Copy the marked text to the X11 selection buffer or OS X clipboard.
`C`	Clear all marked lines.

Display

Keybinding	Description
`?`	View/leave the builtin message.
`q`	Leave the current view or quit the program when in the log file view.
`Q`	Return to the previous view/quit while matching the top times of the two views
`a`	Restore the view that was previously popped with `Q` or `Q`
`A`	Restore the view that was previously popped with `Q` or `Q` and match the top times of the views
`t`	Switch to/from the text file view. The text file view is for any files that are not recognized as log files.
`T`	Toggle the display of the “elapsed time” column that shows the time elapsed since the beginning of the logs or the offset from the previous bookmark. Sharp changes in the message rate are highlighted by coloring the separator between the time column and the log message. A red highlight means the message rate has slowed down and green means it has sped up. You can use the “s/S” hotkeys to scan through the slow downs.
`i`	View/leave a histogram of the log messages over time. The histogram counts the number of displayed log lines for each bucket of time. The bars are layed out horizontally with colored segments representing the different log levels. You can use the `Z` hotkey to change the size of the time buckets (e.g. ten minutes, one hour, one day).
`I`	Switch between the log and histogram views while keeping the time displayed at the top of each view in sync. For example, if the top line in the log view is “11:40”, hitting `I` will switch to the histogram view and scrolled to display “11:00” at the top (if the zoom level is hours).
`v`	Switch to/from the SQL result view.
`V`	Switch between the log and SQL result views while keeping the top line number in the log view in sync with the log_line column in the SQL view. For example, doing a query that selects for “log_idle_msecs” and “log_line”, you can move the top of the SQL view to a line and hit `V` to switch to the log view and move to the line number that was selected in the “log_line” column.
`p`	Enable or disable the display of the fields that the log message parser knows about or has discovered. This overlay is temporarily enabled when the semicolon key (`;`) is pressed so that it is easier to write queries.
`P`	Switch to/from the pretty-printed view of the displayed log or text files
`X`	Close the current text file or log file.
`z` or `Z`	Zoom in or out one step in the histogram view.
`TAB` or `Shift`+`TAB`	In the SQL result view, cycle through the columns that are graphed. Initially, all number values are displayed in a stacked graph. Pressing TAB will change the display to only graph the first column. Repeatedly pressing TAB will cycle through the columns until they are all graphed again.
`Ctrl`+`l`	Switch to lo-fi mode. The displayed log lines will be dumped to the terminal without any decorations so they can be copied easily.
`Ctrl`+`w`	Toggle word-wrapping.
`F2`	Toggle mouse support.

Session

Keybinding	Description
`Ctrl`+`R`	Reset the session state. This will save the current session state (filters, highlights) and then reset the state to the factory default.

Query

Keybinding	Description
`/`<regexp>	Start a search for the given regular expression. The search is live, so when there is a pause in typing, the currently running search will be canceled and a new one started. History is maintained for your searches so you can rerun them easily. Words that are currently displayed are also available for tab-completion, so you can easily search for values without needing to copy-and-paste the string. If there is an error encountered while trying to interpret the expression, the error will be displayed in red on the status line. While the search is active, the 'hits' field in the status line will be green, when finished it will turn back to black. Note: The regular expression format used by is PCRE (Perl-Compatible Regular Expressions). For example, if you wanted to search for ethernet device names, regardless of their ID number, you can type: `eth\d+` You can find more information about Perl regular expressions at: http://perldoc.perl.org/perlre.html If the search string is not valid PCRE, a search is done for the exact string instead of doing a regex search.
`;`<sql>	Execute an SQL query. Most supported log file formats provide a sqlite virtual table backend that can be used in queries. See the SQL section below for more information.
`:`<command>	Execute an internal command. The commands are listed below. History is also supported in this context as well as tab-completion for commands and some arguments. The result of the command replaces the command you typed.
`\|`	Execute an lnav script located in a format directory.
`Ctrl`+`]`	Abort command-line entry started with `/`, `:` or `;`.

Internal Commands

See the lnav Command Reference for a complete list of internal commands.

The commands open, pipe-to, pipe-line-to and write-*-to can be disabled by setting the environment variable LNAVSECURE globally or before starting lnav.

Before entering an internal command press : to enter the lnav command mode.

Filtering

The set of log messages that are displayed in the log view can be controlled with the following commands:

Command	Description
`filter-in <regex>`	Only display log lines that match a regex.
`filter-out <regex>`	Do not display log lines that match a regex.
`disable-filter <regex>`	Disable the given filter.
`enable-filter <regex>`	Enable the given filter.
`delete-filter <regex>`	Delete the filter.
`set-min-log-level <level>`	Only display log lines with the given log level or higher.
`hide-lines-before <abs-time\|rel-time>`	Hide lines before the given time.
`hide-lines-after <abs-time\|rel-time>`	Hide lines after the given time.
`show-lines-before-and-after`	Show lines that were hidden by the “hide-lines” commands.

Navigation

Command	Description
`goto <line#\|N%\|abs-time\|relative-time>`	Go to the given line number, N percent into the file, the given timestamp in the log view, or by the relative time (e.g. “a minute ago”).
`relative-goto <line#\|N%>`	Move the current view up or down by the given amount.
`next-mark error\|warning\|search\|user\|file\|partition`	Move to the next bookmark of the given type in the current view.
`prev-mark error\|warning\|search\|user\|file\|partition`	Move to the previous bookmark of the given type in the current view.

Time

Command	Description
`adjust-log-time <date>`	Change the timestamps for a log file.
`unix-time <secs-or-date>`	Convert a unix-timestamp in seconds to a human-readable form or vice-versa.
`current-time`	Print the current time in human-readable form and as a unix-timestamp.

Display

Command	Description
`help`	Display the built-in help text.
`disable-word-wrap`	Disable word wrapping in the log and text file views.
`enable-word-wrap`	Enable word wrapping in the log and text file views.
`highlight <regex>`	Colorize text that matches the given regex.
`clear-highlight <regex>`	Clear a previous highlight.
`spectrogram <numeric-field>`	Generate a spectrogram for a numeric log message field or SQL result column. The spectrogram view displays the range of possible values of the field on the horizontal axis and time on the vertical axis. The horizontal axis is split into buckets where each bucket counts how many log messages contained the field with a value in that range. The buckets are colored based on the count in the bucket: green means low, yellow means medium, and red means high. The exact ranges for the colors is computed automatically and displayed in the middle of the top line of the view. The minimum and maximum values for the field are displayed in the top left and right sides of the view, respectively.
`switch-to-view <name>`	Switch to the given view name (e.g. log, text, …)
`zoom-to <zoom-level>`	Set the zoom level for the histogram view.
`redraw`	Redraw the window to correct any corruption.

SQL

Command	Description
`create-logline-table <table-name>`	Create an SQL table using the top line of the log view as a template. See the Extracting Data section for more information.
`delete-logline-table <table-name>`	Delete a table created by create-logline-table.
`create-search-table <table-name> [regex]`	Create an SQL table that extracts information from logs using the provided regular expression or the last search that was done. Any captures in the expression will be used as columns in the SQL table. If the capture is named, that name will be used as the column name, otherwise the column name will be of the form “col_N”.
`delete-search-table <table-name>`	Delete a table that was created with create-search-table.

Output

Command	Description
`append-to <file>`	Append any bookmarked lines in the current view to the given file.
`write-to <file>`	Overwrite the given file with any bookmarked lines in the current view. Use `-` to write the lines to the terminal.
`write-csv-to <file>`	Write SQL query results to the given file in CSV format. Use `-` to write the lines to the terminal.
`write-json-to <file>`	Write SQL query results to the given file in JSON format. Use `-` to write the lines to the terminal.
`pipe-to <shell-cmd>`	Pipe the bookmarked lines in the current view to a shell command and open the output in lnav.
`pipe-line-to <shell-cmd>`	Pipe the top line in the current view to a shell command and open the output in lnav.

Miscellaneous

Command	Description
`echo [-n] <msg>`	Display the given message in the command prompt. Useful for scripts to display messages to the user. The `-n` option leaves out the new line at the end of the message.
`eval <cmd>`	Evaluate the given command or SQL query after performing environment variable substitution. The argument to eval must start with a colon, semi-colon, or pipe character to signify whether the argument is a command, SQL query, or a script to be executed, respectively.

Configuration

Command	Description
`config <option>`	Get the current value of a configuration option.
`config <option> <value>`	Set the value of a configuration option.
`reset-config <option>`	Reset a configuration option to the default.
`save-config`	Save the current configuration to `~/.lnav/config.json`.

bityard Wiki

Menu

Syndiaction / RSS Feed

A word from our sponsors

Table of Contents

Introduction

Links

General

Docs

Files and Directories

General Files and Directories

Configuration Files

Getting Help

Install

Configuration

Usage

Command Line Parameters

Display

Navigation

Spatial Navigation

Chronological Navigation

Bookmarks

Display

Session

Query

Internal Commands

Filtering

Navigation

Time

Display

SQL

Output

Miscellaneous

Configuration

SQL Queries

Recipies

Known Issues

bityard Wiki

Menu

Syndiaction / RSS Feed

A word from our sponsors

Table of Contents

Introduction

Links

General

Docs

Files and Directories

General Files and Directories

Configuration Files

Getting Help

Install

Configuration

Usage

Command Line Parameters

Display

Navigation

Spatial Navigation

Chronological Navigation

Bookmarks

Display

Session

Query

Internal Commands

Filtering

Navigation

Time

Display

SQL

Output

Miscellaneous

Configuration

SQL Queries

Recipies

Known Issues

Page Tools