DHIVA LABS · LEARN

Appearance

Troubleshooting and FAQ ​

Causes and fixes for the problems you are most likely to meet, followed by common questions.

Starting LogLens ​

Error: Missing argument 'FILES...'. ​

You ran loglens without a file name. Name at least one log file: loglens app.log.

Error: Invalid value for 'FILES...': Path 'app.log' does not exist. ​

LogLens only opens files that already exist when it starts. Check the spelling and the folder you are in. If the program that writes the log has not created it yet, start that program first, or create an empty file with touch app.log.

If you start LogLens on an empty file, it treats the file as the generic format, because it decides the format from the content at start-up. Start LogLens after a few lines have been written for best results.

loglens: command not found ​

The command is installed inside the virtual environment you created during the install. Activate it again in each new terminal:

bash
source /path/to/loglens/.venv/bin/activate

Reading system logs under /var/log ​

Some logs, such as those under /var/log, can only be read by root or members of a group like adm. LogLens needs read permission like any other program. Ask your administrator to add you to the right group rather than running a terminal app as root.

pip install loglens cannot find the package ​

LogLens is not on PyPI. Install it from the GitHub repository; see Install.

While it runs ​

No colours, or strange characters ​

Use a terminal that supports colour and UTF-8, such as GNOME Terminal, Konsole, the macOS Terminal or iTerm2. Check that TERM is not set to dumb.

Errors-only shows nothing, but I can see error lines ​

LogLens decides levels by format (see Log formats). Some cases to check:

  • In nginx access logs, only 5xx statuses count as errors; 4xx are warnings.
  • In syslog files, the level comes from words in the message. A message that says only CRITICAL is not marked as an error, because syslog lines are checked for error, fail, failed, failure, warn, warning and debug.
  • In JSON lines, the level must be in a level, lvl, severity or log.level field.

The last line of a traceback disappears under errors-only ​

Python tracebacks end with a line such as ValueError: invalid item state. That line is not indented, so in the generic format it is not joined to the error above it and is hidden under errors-only. It is still in the buffer and visible with errors-only off.

I cannot scroll back to older lines ​

The view draws the newest 1,000 lines that pass your filters. Older lines are still in memory (up to 100,000) and you can reach them with search (s) or the clusters panel (c), which jump to the line.

Search says no matches, but the text is in the log ​

Search only looks at lines that the current filter and errors-only setting let through. Clear the filter with Esc and turn errors-only off with e, then search again. Remember that matching is case-sensitive unless you start the pattern with (?i).

Export says file exists: ​

LogLens never overwrites a file. Change the name in the box and press Enter again.

Questions ​

Does LogLens change my log files? ​

No. It only reads them. The only file it writes is an export, and only when you press w and Enter.

What happens when a log is rotated? ​

LogLens notices when a file shrinks (truncation) or is renamed and replaced with a new file, the way logrotate does it, and carries on from the start of the new file. If a file is deleted, LogLens waits and reads it from the beginning if it comes back.

Can I add files while it runs? ​

No. Quit with q and start LogLens again with the new list of files.

Can I read from a pipe, such as journalctl -f | loglens? ​

No. LogLens takes file names only. You can send a stream to a file first, for example journalctl -f > journal.log, and open that file in LogLens in another terminal.

Is anything saved between sessions? ​

No. Filters, searches and the buffer are lost when you quit. Use export to keep lines.

Does it run on Windows? ​

Windows is not tested. LogLens is built and tested for Linux on x86-64 and ARM64, and runs in macOS terminals.

Where do I report a bug? ​

On the LogLens issues page. Include your LogLens version (loglens --version), your Python version and a few sample lines of the log that misbehaves.

Next steps ​