tailspin
4.0.0
A log file highlighter
View (or tail) any log file of any format
No setup or config required
Highlights numbers, dates, IP-addresses, UUIDs, URLs and more
All highlight groups are customizable
Easy to integrate with other commands
Uses less under the hood
Powered by the manifold crate
Overview
Usage
Installing
Highlight Groups
Watching folders
Customizing Highlight Groups
Working with stdin and stdout
Using the pager less
Settings
tailspin works by reading through a log file line by line, running a series of regexes
against each line. The regexes recognize patterns you expect to find in a logfile, like dates, numbers, severity
keywords and more.
tailspin does not make any assumptions on the format or position of the items it wants to highlight. For this reason,
it requires no configuration and the highlighting will work consistently across different logfiles.
The binary name for tailspin is tspin.
# Read from file and view in `less`tspin application.log# Read from file and print to stdouttspin application.log --print# Read from stdin and print to stdoutkubectl logs [pod name] --follow | tspin# Capture the stdout of another command and view in `less`tspin --listen-command 'kubectl logs -f pod_name'
# Homebrewbrew install tailspin# Cargocargo install tailspin# Archlinuxpacman -S tailspin# Nixnix-shell -p tailspin# NetBSDpkgin install tailspin# FreeBSDpkg install tailspin
cargo install --path .
Binary will be placed in ~/.cargo/bin, make sure you add the folder to your PATH environment variable.
Important
When building from source, make sure that you are using the latest version
of less.
tailspin can listen for newline entries in a given folder. Watching folders is useful for monitoring log files that
are rotated.
When watching folders, tailspin will start in follow mode (abort withCtrl + C) and will only print
newline entries which arrive after the initial start.
Create a theme.toml in ~/.config/tailspin to customize highlight groups.
Styles have the following shape:
style = { fg = "color", bg = "color", italic = false, bold = false, underline = false }To edit the different highlight groups, include them in your theme.toml file. For example, to edit the datehighlight group, add the following to your theme.toml:
[date]style = { fg = "green" }Expand the section below to see the default config for the highlight groups:
[date]date = { fg = "magenta" }time = { fg = "blue" }zone = { fg = "red" }separator = { faint = true }
[[keywords]]words = ['null', 'true', 'false']style = { fg = "red", italic = true }
[[keywords]]words = ['GET']style = { fg = "black", bg = "green" }
[url]http = { fg = "red", faint = true }https = { fg = "green", faint = true }host = { fg = "blue", faint = true }path = { fg = "blue" }query_params_key = { fg = "magenta" }query_params_value = { fg = "cyan" }symbols = { fg = "red" }
[number]style = { fg = "cyan" }
[ip]number = { fg = "blue", italic = true }letter = { fg = "magenta", italic = true }separator = { fg = "red" }
[quotes]style = { fg = "yellow" }token = '"'[path]segment = { fg = "green", italic = true }separator = { fg = "yellow" }
[uuid]number = { fg = "blue", italic = true }letter = { fg = "magenta", italic = true }separator = { fg = "red" }
[pointer]number = { fg = "blue", italic = true }letter = { fg = "magenta", italic = true }separator = { fg = "red" }
[key_value]key = { faint = true }separator = { fg = "white" }
[process]name = { fg = "green" }separator = { fg = "red" }id = { fg = "yellow" }
[json]key = { fg = "yellow" }quote_token = { fg = "yellow", faint = true }curly_bracket = { faint = true }square_bracket = { faint = true }comma = { faint = true }colon = { faint = true }To individually disable or enable highlight groups, use the --enable and --disable flags:
# Enable only the url highlight group, disabling the resttspin application.log --enable=url# Disable the numbers highlight group, keeping the resttspin application.log --disable=numbers
To add custom keywords, either include them in the list of keywords or add new entries:
[[keywords]]words = ['MyCustomKeyword']style = { fg = "green" }
[[keywords]]words = ['null', 'true', 'false']style = { fg = "red", italic = true }Sometimes it is more convenient to add highlight groups on the fly without having to edit a TOML. To add highlights from
the command line, use the --words-[red|green|yellow|blue|magenta|cyan] flag followed by a comma separated list
of words to be highlighted.
When you need more control over the highlighting, you can use the regex highlighter. This highlighter allows you to specify a regex and a style to be applied to the matched text.
It supports one capture group (). When found, it will apply the style to the captured text.
[[regexps]]regex = 'Started (.*).'style = { fg = "red" }stdin and stdoutBy default, tailspin will open a file in the pager less. However, if you pipe something into tailspin, it will
print the highlighted output directly to stdout. This is similar to running tspin [file] --print.
To let tailspin highlight the logs of different commands, you can pipe the output of those commands into tailspinlike so:
journalctl -f | tspincat /var/log/syslog | tspinkubectl logs -f pod_name | tspin
lessTo capture the output of a command and view it in less, use the --listen-command flag:
tspin --listen-command 'kubectl logs -f pod_name'
This will run the command kubectl logs -f pod_name in the background and pipe the output to tailspin. The output
will be displayed in less, allowing you to navigate and search through the logs.
lesstailspin uses less as its pager to view the highlighted log files. You can get more info on less via the mancommand (man less) or by hitting thehbutton to access the help screen.
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:
j/k: Scroll one line up / down
d/u: Scroll one half-page up / down
g/G: Go to the top / bottom of the file
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 withCtrl + 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, pressShift + F.
Use/followed by your search query. For example, /ERROR finds the first occurrence ofERROR.
After the search,nfinds the next instance, andNfinds the previous instance.
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.
-f, --follow Follow the contents of the file-e, --start-at-end Start at the end of the file-p, --print Print the output to stdout-c, --listen-command '[CMD]' Listen the output (stdout) of the provided command --config-path [PATH] Use the configuration file from the provided path --words-[COLOR] [WORDS] Highlight the provided words with the given color --no-builtin-keywords Disable the highlighting of booleans, nulls, log severities and common REST verbs --enable=[HIGHLIGHT_GROUP] Enable one or more highlight groups, disabling the rest --disable=[HIGHLIGHT_GROUP] Disable one or more highlight groups, enabling the rest
