DHIVA LABS · LEARN

Appearance

Beginner guide ​

By the end of this guide you will have watched two growing log files in one LogLens window, narrowed the view to the lines you care about, paused to search, and grouped the errors.

What you need ​

  • LogLens installed from source, with its virtual environment active. See Install.
  • A terminal in the cloned loglens folder. The guide uses the sample log script, scripts/genlog.py, that ships in that folder.

You do not need any real logs. The script writes made-up but realistic log lines, including errors with Python tracebacks.

Start two sample logs ​

  1. Start a sample application log that grows by 10 lines a second, in the background:

    bash
    python3 scripts/genlog.py app.log --format generic --rate 10 &

    The & at the end runs the script in the background, so you get your prompt back. The script writes to app.log until you stop it.

  2. Start a sample web server log that grows by 5 lines a second:

    bash
    python3 scripts/genlog.py api.log --format nginx --rate 5 &

    This file uses the nginx access log format: one line per web request, with an HTTP status code.

WARNING

genlog.py empties the file you name before it starts writing. Only give it a new file name, never the name of a log you want to keep.

Open LogLens ​

  1. Point LogLens at both files:

    bash
    loglens app.log api.log

    The window fills with the last 50 lines of each file, then new lines keep arriving at the bottom.

  2. Read the top line. It is the status bar. It shows the version, one coloured label per file, and lines: followed by the number of lines read so far.

  3. Read a log line. Each one starts with the file's label in square brackets, in that file's colour, then the time, then the original line:

    text
    [app.log] 14:22:02 2026-11-09 14:22:02,118 ERROR app.core: unhandled exception in request handler

    Error lines are red, warnings yellow and debug lines dim. Traceback lines under an error are dim too.

  4. Look at the bottom line. It is the footer, listing the main keys: Quit, Filter, Search, Errors, Pause, Histogram, Clusters and Export.

The project README shows the kind of screen you get (this example uses different files):

text
 LogLens v0.2.0  [app.log ]  [api.log ]  lines: 8421

 [app.log ] 14:22:01 INFO  request completed in 42ms
 [api.log ] 14:22:01 WARN  retrying after backoff of 2s
 [app.log ] 14:22:02 ERROR unhandled exception in request handler
 [app.log ] 14:22:02 Traceback (most recent call last):
 [app.log ] 14:22:02   File "app/core/handler.py", line 88, in process_request
 [app.log ] 14:22:02 ValueError: invalid item state
 [api.log ] 14:22:03 INFO  cache miss for key user:4821

 errors/min · 15m · peak 4        ▁▂▃▅█▃▂▁▁▂▃▄▂▁▁

Narrow the view ​

  1. Press /. A box opens at the bottom: regex filter — Enter keeps, Esc clears.

  2. Type POST. As you type, the view shrinks to the lines that contain POST. The status bar shows /POST/.

  3. Press Enter. The box closes and the filter stays on.

  4. Press Esc. The filter is cleared and every line comes back.

  5. Press e. Now only errors are shown, each with its traceback underneath. The status bar shows ERRORS. Press e again to see everything.

In the nginx file, LogLens counts a 5xx status as an error and a 4xx status as a warning, so a 500 request shows up under Errors and a 404 does not.

  1. Press p. The status bar shows PAUSED. New lines are still collected, but the view stops moving.

  2. Scroll with ↑, ↓, PgUp and PgDn.

  3. Press s, type timeout and press Enter. LogLens jumps to the newest line that contains timeout and highlights every match in yellow. The status bar shows the match number, for example ?timeout? match 12/12.

  4. Press n to go to the next older match, and N (Shift + n) to go back to a newer one.

  5. Press p to resume. The search is cleared and the view jumps back to the newest lines.

Find the most common errors ​

  1. Press t. A small chart appears with the label errors/min · 15m · peak and a number: one bar per minute for the last 15 minutes. Press t again to hide it.

  2. Press c. The error clusters panel opens. Each row is a group of similar errors, with a count such as [×14], a title, how many files it came from and when it was last seen. The biggest group is at the top.

  3. Use ↑ and ↓ to pick a row and press Enter. The panel closes, LogLens pauses, and the view jumps to the newest error in that group.

Save what you found ​

  1. Press e to show errors only.

  2. Press w. The export box opens with a file name already filled in, such as loglens-export-20261109-142530.log.

  3. Press Enter. A message says how many lines were written and where. The file holds the original lines, without the coloured labels.

Finish ​

  1. Press q to quit LogLens.

  2. Stop the two sample scripts:

    bash
    kill %1 %2

  3. Delete the sample files if you like: rm app.log api.log.

What you learned ​

  • loglens takes one or more file names and merges them into one live view.
  • / filters, e shows errors only, p pauses, s searches.
  • t charts errors per minute, c groups similar errors, w saves the current view.
  • Esc closes whatever is open, and clears the filter when nothing is.

Next steps ​