lnav (The Logfile Navigator)

lnav is a terminal-based logfile navigator composed of several core components:

• Log File Parser: Detects and parses log formats.
• Text UI: A terminal interface built on top of notcurses for viewing logs.
• SQLite Integrations: Provides programmatic access to messages and internal state via SQLite virtual-tables.
• Command-Line Interface (CLI): For interacting with lnav.
• Log Commands: Specialized commands for operating on log data.

The central data structure is the combined log message index, which is populated as new messages are read. The Text UI displays a subset of this index, while SQLite allows for complex querying.

lnav automatically detects log formats during scanning. It includes over 70 built-in formats such as:

• Common Web Access Log
• W3C Extended Log File Format
• logfmt
• Syslog, Glog, dpkg.log, journald (JSON)
• CUPS page_log, uwsgi, Caddy
• Cloudflare Enterprise access logs
• OpenTelemetry Collector, OTLP Python
• Rust tracing, Bunyan, Pino
• VMware ESXi/vCenter Logs
• MongoDB, MySQL (error/general/slow), PostgreSQL
• Strace, sudo (via syslog)
• "Generic" (any message starting with a timestamp)

GZIP'ed and BZIP2'ed files are also detected and decompressed on-the-fly. If you have a JSON-lines file or a format matchable by PCRE, you can define custom formats using a JSON file.

lnav is purpose-built for log files and is designed to be competitive with or superior to standard utilities like vim, less, and shell pipelines. Key performance features include:

• Indexing: lnav creates an index entry for each line, allowing for immediate jumps by time, log level, and line number. While this results in a medium memory footprint, it provides immediate UI feedback and progress indicators during file loading.
• Background Searching: Searches run in the background with a progress bar, preventing the UI from becoming unresponsive.
• Filtering: When filtering, lnav updates its index and provides activity feedback while evaluating the filter.
• Statistics: lnav can perform complex statistical queries (e.g., counting unique values) using PRQL. Results are displayed in a DB view with visual aids like bar charts.

When lnav accesses a remote host, it automatically transfers an agent (called the "tailer") to that host. This agent is an actually portable executable compatible with most X86 Operating Systems.

The agent performs the following tasks:

• Monitors files of interest.
• Synchronizes file contents back to the local lnav host.
• Handles interactive requests for TAB-completion of remote file paths.
• Enables previewing of directory and file contents.

The lnav external-access server provides a REST API designed for remote control of an lnav instance. It allows external applications to:

1. Execute lnav scripts.
2. Retrieve information about the current state of the lnav Terminal User Interface (TUI).

This server is intended for integration with other applications that need to interact with a running lnav session. For detailed technical specifications, refer to the official External Access documentation.

lnav parses log files based on format definitions stored in configuration files. When you load a file, lnav checks it against available formats by attempting to parse the first few lines.

• Matched Format: Once a format matches the initial lines, it is used to parse the entire file.
• No Match: If no format matches, the file is treated as plain text and can be viewed using the t key (text view).

If you are using an SSH connection or your environment does not support a native clipboard, you can use "lo-fi" mode to bypass the curses display and print raw text directly to the terminal.

• In a view: Press CTRL-L to switch the current view to lo-fi mode.
• Via commands: Prefix your command with a dash - to switch to lo-fi mode and print the output to standard out.

Starting from version 0.11.0, lnav provides improved, compiler-style error messages. When a syntax error occurs (for example, in a SQL file), lnav displays a syntax-highlighted code snippet with a pointer to the specific part of the code causing the error.

Inside the Terminal User Interface (TUI), these long-form error messages are displayed in a dedicated panel at the bottom of the screen. This panel automatically disappears after a short period or once user input is received.

In lnav (v0.8.4 and later), you can identify the origin of log messages using keyboard navigation:

1. Press the left-arrow key once to reveal the unique name of the source file.
2. Press the left-arrow key a second time to reveal the full file path.