Reference

Every option, key, indicator and limit in LogLens 0.2.0.

Command line

loglens [OPTIONS] FILES...

Argument or option	What it does
FILES...	One or more log files to tail. Required. Each must exist and must be a file, not a folder.
--version	Prints loglens, version 0.2.0 and exits.
--help	Prints the usage text and exits.

There are no other options and no configuration file. Format detection, colours and limits are automatic.

Each file gets a label from its file name. When two files share a name, the label adds the parent folder, for example web/access.log and api/access.log. Labels are coloured in turn cyan, magenta, green, yellow, blue and bright red, then the colours repeat.

Key bindings

Key	Action
/	Open the regex filter. It applies as you type. Enter keeps it, Esc clears it.
e	Turn errors-only on or off. Traceback lines stay with their error.
p	Pause or resume. Resuming clears any active search.
s	Open buffer search. Enter jumps to the newest match and pauses.
n	Next older match, wrapping to the newest.
N	Next newer match, wrapping to the oldest.
t	Show or hide the error histogram.
c	Open the error clusters panel. In the panel, c closes it.
w	Open export, with a timestamped file name filled in. Enter writes the file.
q	Quit.
↑ ↓ PgUp PgDn	Scroll the log view, or move through the clusters list.
Enter	In the clusters panel: jump to the newest error in the selected group and pause.
Esc	Closes or clears one thing; see below.

Esc does the first of these that applies:

1. Closes the clusters panel.
2. Closes the export box.
3. Closes the search box.
4. Clears the active search.
5. Clears the regex filter.

Status bar

The top line always shows LogLens v0.2.0, the label of each file, and lines: with the number of lines read since start-up. It adds these when they apply:

Indicator	Meaning
PAUSED	The view is paused.
ERRORS	Errors-only is on.
/pattern/	A regex filter is active.
invalid regex	The text in the filter box is not a valid pattern. The last valid filter still applies.
?pattern? match 3/12	A search is active: match 3 of 12, counted from the oldest.
?pattern? no matches	A search is active but found nothing.
invalid search regex	The search pattern is not valid.

Log formats

LogLens reads up to the first 8 KB of each file when it starts and picks the format that fits best. Each file is detected on its own, so different files can use different formats. The choice is made once, at start-up.

Format	Recognised by	How the level is found
JSON lines	Each line is a JSON object	From level, lvl, severity or log.level, the first one present.
Syslog (RFC 3164)	A Mon DD HH:MM:SS host proc[pid]: message header	From words in the message: error, fail, failed or failure give ERROR; warn or warning give WARN; debug gives DEBUG. Otherwise no level.
nginx access log (combined)	ip - - [time] "METHOD path HTTP/x.x" status bytes "referer" "agent"	From the HTTP status: 5xx is ERROR, 4xx is WARN, anything else INFO.
nginx error log	yyyy/mm/dd hh:mm:ss [level] pid#tid: message	From the level in square brackets.
Generic (fallback)	A leading timestamp, or a level word anywhere in the line	From the first level word in the line.

For JSON lines, the time comes from ts, time, timestamp or @timestamp (ISO 8601, or seconds or milliseconds since 1970) and the message from msg, message or event.

In the generic format, a line that is indented, or starts with Traceback (most recent call last), File or at , is joined to the record above it and shares its level.

Level words are matched without regard to case. WARN and WARNING count as WARN. ERROR, ERR, CRITICAL, CRIT, FATAL, ALERT and EMERG all count as ERROR.

The time shown in front of each line is the time parsed from the line when there is one, otherwise the time LogLens read the line.

Colours

Level	Colour
ERROR	Bold red
WARN	Yellow
DEBUG	Dim
INFO, or no level	Normal
Traceback and continuation lines	Dim

Limits

Item	Value
Lines kept in memory	100,000 per session; the oldest are dropped first
Lines loaded from each file at start-up	The last 50
Lines drawn in the view	The newest 1,000 that pass the filters
Format detection sample	First 8 KB of each file
Histogram	15 one-minute bars, updated every second
Clusters panel refresh	Every 2 seconds, when new lines have arrived

Export file names

The default export name is loglens-export-YYYYMMDD-HHMMSS.log, using the local date and time. A relative path is saved relative to the folder you started LogLens from. Existing files are never overwritten.

Sample log generator

The source folder includes scripts/genlog.py, which writes sample log lines for trying LogLens. It needs only Python.

python3 scripts/genlog.py OUTPUT [--format F] [--count N] [--rate R]
                          [--error-rate X] [--seed N] [--rotate-every N]

Option	Default	What it does
OUTPUT		The file to write. It is emptied first.
--format F	mixed	json, syslog, nginx, generic or mixed (a random mix of all four).
--count N	run forever	Stop after N entries.
--rate R	10	Entries per second.
--error-rate X	0.1	Share of entries that are errors, from 0 to 1.
--seed N	random	Seed, so the same output can be produced again.
--rotate-every N	off	Empty the file after every N entries, to test rotation handling.

Stop it with Ctrl + C.

Next steps

• Filter, search and pause
• Troubleshooting and FAQ