Repository files navigation

A log file highlighter

• 🪵 View (ortail) 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
• 🔍 Usesless under the hood
• 📦 Powered by themanifold crate

• Overview
• Usage
• Installing
• Highlight Groups
• Watching folders
• Customizing Highlight Groups
• Working withstdin andstdout
• Using the pagerless
• Settings

tailspin works by reading through a log file line by line, running a series of regexesagainst each line. The regexes recognize patterns you expect to find in a logfile, like dates, numbers, severitykeywords 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 fortailspin istspin.

#Read from file and viewin`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 anothercommand and viewin`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#Windowsscoop install tailspin

cargo install --path .

Binary will be placed in~/.cargo/bin, make sure you add the folder to yourPATH environment variable.

tailspin can listen for newline entries in a given folder. Watching folders is useful for monitoring log files thatare rotated.

When watching folders,tailspin will start in follow mode (abort withCtrl + C) and will only printnewline entries which arrive after the initial start.

Create atheme.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 yourtheme.toml file. For example, to edit thedatehighlight group, add the following to yourtheme.toml:

[date]style = {fg ="green" }

Expand the section below to see the default config for the highlight groups:

[dates]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" }[urls]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" }[numbers]style = {fg ="cyan" }[ip_addresses]number = {fg ="blue",italic =true }letter = {fg ="magenta",italic =true }separator = {fg ="red" }[quotes]style = {fg ="yellow" }token ='"'[paths]segment = {fg ="green",italic =true }separator = {fg ="yellow" }[uuids]number = {fg ="blue",italic =true }letter = {fg ="magenta",italic =true }separator = {fg ="red" }[pointers]number = {fg ="blue",italic =true }letter = {fg ="magenta",italic =true }separator = {fg ="red" }[key_value_pairs]key = {faint =true }separator = {fg ="white" }[processes]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 fromthe command line, use the--words-[red|green|yellow|blue|magenta|cyan] flag followed by a comma separated listof words to be highlighted.

When you need more control over the highlighting, you can use the regex highlighter. This highlighter allows you tospecify 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.

[[regexes]]regex ='Started (.*)\.'style = {fg ="red" }

By default,tailspin will open a file in the pagerless. However, if you pipe something intotailspin, it willprint the highlighted output directly tostdout. This is similar to runningtspin [file] --print.

To lettailspin highlight the logs of different commands, you can pipe the output of those commands intotailspinlike so:

journalctl -f | tspincat /var/log/syslog | tspinkubectl logs -f pod_name | tspin

To capture the output of a command and view it inless, use the--listen-command flag:

tspin --listen-command 'kubectl logs -f pod_name'

This will run the commandkubectl logs -f pod_name in the background and pipe the output totailspin. The outputwill be displayed inless, allowing you to navigate and search through the logs.

tailspin usesless as its pager to view the highlighted log files. You can get more info onless via themancommand (man less) or by hitting theh button to access the help screen.

Navigating withinless uses a set of keybindings that may be familiar to users ofvim or othervi-likeeditors. 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 runtailspin with the-f or--follow flag, it will scroll to the bottom and print new lines to the screenas they're added to the file.

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

To resume following the file from withinless, pressShift + F.

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

After the search,n finds the next instance, andN finds the previous instance.

less allows filtering lines by a keyword, using& followed by the pattern. For instance,&ERROR showsonly lines withERROR.

To only show lines containing eitherERROR orWARN, 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