log_view

log_viewer is an ncurses text UI for viewing rosout logs.

Motivation

Receive, filter, and navigate through all published rosout log messages from within a terminal to support debugging a robot live.

Problem

Many rosout log messages don’t get printed to the terminal in the normal course when there are lots of nodes/messages. There is also not a convenient way to filter and navigate through them in real time.

swri_console provides most of the desired functionality very well, but is Qt based and requires a graphical interface.

Solution

log_viewer is very similar in concept and design to swri_console, but uses ncurses instead of Qt for the interface.

Log messages can be filtered based on:

• log level
• node
• whitelist text filter
• exclude text filter
• bag source (when loading from bag files)

log_viewer also supports text searches with three pattern modes (literal, regex, and template) and jumping from match to match.

Log messages are copied to the clipboard by selecting them.

Like swri_console, log_viewer doesn’t need ROS to be running to start and will automatically connect/reconnect when it becomes available.

Loading from Bag Files

log_viewer can load logs directly from one or more rosbag2 bag files instead of subscribing to a live ROS topic:

ros2 run log_view log_viewer /path/to/bag [/path/to/bag2 ...]

In this mode no ROS subscription is created. All messages from the supplied bags are loaded before the viewer starts, sorted chronologically. The status bar shows the log count and the bag source(s) rather than the system time:

logs: 1234 from bag: /path/to/bag

When multiple bags are provided, a bag source filter panel (CTRL-b) becomes available. It lists each bag with its message count and lets you toggle individual bags on or off to include or exclude their messages from the view. Within the panel, pressing i inverts the selection and CTRL-a selects all bags.

Log Persistence

log_viewer can optionally persist log messages to disk and reload them on startup. This is useful for preserving log history across sessions.

Log files are stored under <workspace>/.log_view/ as timestamped text files (log_view_YYYYMMDD_HHMMSS.log), where <workspace> is derived from the COLCON_PREFIX_PATH environment variable set when a ROS 2 workspace is sourced. This keeps logs isolated per workspace. The format is human-readable and can be inspected with standard tools such as cat, grep, and less.

Persistence is automatically disabled if COLCON_PREFIX_PATH is not set or does not point to a valid directory.

Session boundaries are marked in the log with separator lines:

-------- Session Started At 2026-05-04 09:15:00 --------
-------- Recording Ended At 2026-05-04 09:47:23 --------

Log persistence is configured in the preferences panel (CTRL-k):

Clearing the message history (CTRL-r) also deletes all persisted log files.

Pattern Syntax

Filter, exclude, and search inputs all support the same three matching modes:

Template placeholders:

File truncated at 100 lines see the full file

Changelog for package log_view

Forthcoming

• Add structured pattern matching for filter, exclude, and search inputs supporting three modes:
  • Literal (default): case-insensitive substring match.
  • Regex: /pattern/ or /pattern/i (case-insensitive flag).
  • Template: fixed text with {placeholder} gaps for numeric comparisons ({>N}, {<N}, {>=N}, {<=N}, {=N}, {N..M}), token alternation ({a|b|c}), and wildcards ({*} or {}).
• Add single-step match navigation with n (next match) and N (previous match).
• Add match counter to the status bar as match: N of M.
• Add blinking highlight on the current search match row; off-screen indicators (</>) also blink for the current match.
• Fix focus initialization when restoring filter and exclude patterns from preferences.

0.5.0 (2026-05-28)

• Add loading logs from one or more bag files.
• Add bag source panel to toggle per bag filtering.
• Fix navigation in node selection panel when the panel has no scroll bar.
• Fix restoring selected whitelist nodes after clearing logs.

0.4.0 (2026-05-22)

• Added subscription to /clock to display sim time on status bar.
• Updated stamp format selection to preview the stamp format change.
• Improved formatting of nodes, preferences, and details panels.
• Improved search navigation.
• Fixed exit to only require a single ctrl-c press.
• Fixed message counts for nodes when loading messages from previous sessions.

0.3.3 (2026-05-20)

• Added support for UTF8 glyphs in log messages.
• Added support for ANSI color codes in log messages.
• Fixed display for terminals limited to 8 colors.
• Fixed session boundaries to not be treated as normal log entries.
• Fixed details panel to scroll vertically when insufficient space is available.
• Fixed help panel to scroll vertically when insufficient space is available.
• Fixed preference panel to scroll vertically when insufficient space is available.
• Updated node panel scrolling to make it consistent with other panels.
• Improved selection controls.

0.3.2 (2026-05-04)

• Scope log and preference storage to the active ROS 2 workspace via COLCON_PREFIX_PATH (stored under <workspace>/.log_view/).
• Show file paths in preferences panel; display a warning when persistence is unavailable.
• Contributors: Marc Alban

0.3.1 (2026-05-04)

• Persist logs to disk in ~/.local/share/log_view/ with configurable rotation and max size.
• Load persisted logs on startup.
• Add preferences panel (CTRL-k) for persistence and filter settings.
• Show filtered log count in status bar (logs: X of Y when a filter is active).
• Contributors: Marc Alban

0.3.0 (2026-03-29)

• Add details panel with per-message metadata display.
• Enable static analysis and linting tests.
• Contributors: Marc Alban

0.2.7 (2026-02-18)

• Replace ament_target_dependencies with target_link_libraries.
• Contributors: Marc Alban

0.2.5 (2024-11-25)

• Fix mvwprintw format-security error
• Contributors: Marc Alban

0.2.4 (2024-07-24)

• Fix build error caused by mvwprintw. (#19)
• Contributors: Marc Alban

0.2.3 (2024-07-08)

• Use default C++ version (#16)
• Disable mouse move events on exit. (#12)

File truncated at 100 lines see the full file