Features

• 🪵 View (or tail) any log file of any format
• 🍰 No setup or config required
• 🌈 Highlight numbers, dates, IP-addresses, UUIDs, URLs and more
• ⚙️ All highlight groups are customizable
• 🔍 Uses less under the hood to provide scrollback, search and filtering

Table of Contents

• Overview
• Installing
• Highlight Groups
• Customizing Highlight Groups
• Using the pager less
• Settings

Overview

tailspin works by reading through a log file line by line, running a series of regexes against each line. The regexes recognize useful patterns, like dates, numbers, severity keywords and more.

Since tailspin does not make any assumptions on the format or position of the items it wants to highlight, it requires no configuration or setup and will work reliably across different log formats.

Installing

# Install
cargo install tailspin

# View log file
spin [file]

# Tail log file
spin -f [file] 

Note When installing via cargo, make sure that $HOME/.cargo/bin is in your PATH environment variable

Highlight Groups

Dates

Keywords

URLs

Numbers

IP Addresses

Quotes

Unix file paths

UUIDs

Customizing Highlight Groups

Overview

tailspin uses a single config.toml file to configure all highlight groups. When customizing highlights it is advised to start with the tailspin generate-config command to place a config.toml with default options in ~/.config/tailspin.

To disable a highlight group, either comment it out or delete it.

Highlights have the following shape:

style = { fg = "color", bg = "color", italic = false, bold = false, underline = false }

Adding Keywords

To add custom keywords, either include them in the list of keywords or add new entries:

[[groups.keywords]]
words = ['MyCustomKeyword']
style = { fg = "green" }

[[groups.keywords]]
words = ['null', 'true', 'false']
style = { fg = "red", italic = true }

Using the pager less

Overview

tailspin uses less as its pager to view the highlighted log files. You can get more info on less via the man command (man less) or by hitting the h button to access the help screen.

Navigating

Navigating within less uses a set of keybindings that may be familiar to users of vim or other vi-like editors. Here's a brief overview of the most useful navigation commands:

Scrolling

• j/k: Scroll one line up/down.
• d/u: Scroll one half-page up/down.

Start and end of file:

• g: Go to the start (top) of the file.
• G: Go to the end (bottom) of the file.

Follow mode

When you run tailspin with the -f or --follow flag, it will scroll to the bottom and print new lines to the screen as they're added to the file.

To stop following the file, interrupt with Ctrl + C. This will stop the tailing, but keep the file open, allowing you to review the existing content.

To resume following the file from within less, press F.

Search

Use / followed by your search query. For example, /ERROR finds the first occurrence of ERROR.

After the search, n finds the next instance, and N finds the previous instance.

Filtering

less allows filtering lines by a keyword, using & followed by the pattern. For instance, &ERROR shows only lines with ERROR.

To only show lines containing either ERROR or WARN, use a regular expression: &\(ERROR\|WARN\).

To clear the filter, use & with no pattern.

Settings

# Commands
generate-config    Create a config file with default settings at ~/.config/tailspin

# Flags
-f, --follow       Follow (tail) the contents of the file
    --config       Provide a path to a custom configuration file