Version 0.29.1, December 2022
hx [OPTIONS] [LOGFILE...]Apache logs, original vs. colored with hx:
Syslog:
hx is a log files highlighter.
Its main purpose is to make long log files with long lines easier to grasp at a glance through simple, consistent coloring.
It will never change any of its input besides adding ANSI color sequences to it (with two exceptions: it will add a very visible dot at the start of every line for better visual line separation, and it will add a dashed separator line once after the stdin input pauses for better visual separation between “old” and “new” lines).
It understands a few more or less commonly-used log entry formats, most importantly the standard syslog format. Apart from that, it can guess some less-defined formats such as a leading timestamp or a trailing error source filename.
It is well suited for handling running logs such as returned by “tail -f /var/log/syslog”.
# make install
This will copy the hx script to /usr/local/bin/hx
and the man page to /usr/local/share/man/man1/hx.1.gz.
The script's internal modules
will be copied to /usr/local/lib/hx-modules/.
- --ecma48
Forces the program to output only basic, ECMA-48-compatible ANSI coloring codes. This will lead to less colorful output but should increase compatibility in case your terminal does not support the extended coloring sequences.
hx makes extensive use of ANSI coloring sequences, including the “CSI 38;5;n m” sequence for extended color selection and the “CSI 38;2;r;g;b m” sequence for RGB true-color selection. They may not be supported by all terminals currently in use. Use the --ecma48 option if you want hx to use ECMA-48-compatible ANSI sequences only. This will lead to less colorful output but should increase compatibility. Alternatively, the HX_COLORS environment variable can be used to manually set all coloring to compatible sequences.
The default colors are optimized for a black terminal background.
Generally the program tries to identify to the main log message part and print it in the terminal's default color (white). All other parts of the log message will be colored differently to visually separate them: the metadata prefix will be yellow, additional information at the end will be grey, and additional information between the yellow metadata prefix and the white message will be yellowish-grey.
The following sections list typical log line parts and how they fit into these broader categories.
Most log lines start with metadata. The program will color all of it yellow. This includes the timestamp, the application name and/or PID, the hostname, the username, and the log level.
This is log metadata considered non-essential or additional information located between the log metadata prefix and the message content, including syslog message IDs, client addresses and usernames, or RFC-5424 structured data. It'll be colored yellowish-grey.
The only part which will be printed in the terminal's standard color (usually white), this is the actual log message content. Any recognized exception class name prefix or error code prefix will also be bolded.
This is data considered non-essential to the log message, including bracketed suffixes, error source file/lineno, stack traces, and JSON error data. It will be colored grey.
- Additionally, all “informational” sections may contain HTTP status codes which will be colored appropriately: 1xx Info/3xx Redirection = yellow, 2xx Success = green, 4xx Client Error = red, 5xx Server Error = pink.
- Similar coloring will be applied to Postfix DSN codes.
- JSON object keys will be bolded.
- File basenames will be bolded.
- The syslog prefix “message repeated N times: [” will be colored blue.
The HX_COLORS environment variable, if set and non-empty, is read on start-up for color definitions which will overwrite the default colors (described in the “Output” section above).
The variable supports section—color assignments like this: “ap=38;5;90”. This assigns the ANSI color 38;5;90 (dark violet) to the ap section (app name/PID).
Multiple assignments must be separated with colons (:). Multiple assignments to the same section overwrite earlier assignments. If the equals sign is not followed by a digit, the trailing part is assumed to be a section name; for example, “ap=hn” assigns the hn (hostname) color to ap (app/PID). The special section name “*” assigns a color definition to all sections not previously assigned in the variable.
- SY
The line-start symbol in case of a normal line. - ML
The line-start symbol in case of a meta line (such as “tail -f” filename headers). Also the meta line content. - CL
The line-start symbol in case of a continuation line. - RP
Syslog repeated message wrapper. - FS
Separator line on input read pause. - dt
Date/time. - ap
Application name or process ID (PID). - hn
Source hostname. - ix
Informational message prefix. - in
Informational message suffix. - le
Log levels error and higher. - lw
Log levels warning and higher. - ll
All other log levels. - ms
Message content. - er
Error class name or error code. - eq
Error class namespace. - tr
Stack traces and error source (file/lineno). - st
Exception stacks. - sm
Exception stack single messages (only if more than one). - fl
File basenames and/or line numbers. - fn
Function names (in stack traces). - jw
Top-level JSON enclosure characters ([] or {}). - ke
Keys in key—value structures such as JSON. - h1
HTTP 1xx status codes (Informational). - h2
HTTP 2xx status codes (Success). - h3
HTTP 3xx status codes (Redirection). - h4
HTTP 4xx status codes (Client Error). - h5
HTTP 5xx status codes (Server Error). - h6
HTTP 4xx status codes considered less important, such as HTTP 404 Not Found. - *
All sections not previously assigned.
By default, hx produces output as if it had been given this HX_COLORS value:
SY=33:CL=38;2;113;97;25:ML=38;2;114;204;204:FS=32;2:RP=34:dt=SY:hn=SY:ap=SY:ms=0:ll=SY:lw=38;5;220:le=38;2;255;145;36:in=38;5;243:ix=38;2;125;117;83:tr=in:st=in:sm=ms:eq=ms:er=1:fl=1:fn=1:jw=1:ke=1:h1=38;2;202;214;98:h2=38;2;98;214;113:h3=h1:h4=38;2;235;41;41:h5=38;5;199;1:h6=38;2;155;72;72
When using the --ecma48 option, hx uses output settings equivalent to these HX_COLORS settings:
SY=33:CL=33;2:ML=36:FS=32;2:RP=34:dt=SY:hn=SY:ap=SY:ms=0:ll=33:lw=33;1:le=33;1:in=37;2:ix=in:tr=in:st=in:sm=ms:eq=ms:er=1:fl=1:fn=1:jw=1:ke=1:h1=33:h2=32:h3=h1:h4=31;1:h5=31;1:h6=31
The HX_SETTINGS environment variable, if set and non-empty, is read on start-up to change various run-time settings.
Boolean options can be switched on simply by including their option keyword and switched off by prefixing them with “no”. For example, the --ecma48 compatibility output mode is enabled by adding the “ecma48” keyword to the variable and explicitly disabled by adding the “noecma48” keyword. Some options take an optional or required value; supply it after an equals sign (=). Option values may be enclosed with doublequotes ("). This is required for values which contain spaces or doublequotes (which must be escaped with backslashes). Multiple option keywords must be separated by one or more spaces.
- ecma48, 48
Enables the compatibility output mode. Equivalent to the --ecma48 command line option.
Default: disabled. - pausewait[=delay], pw
Enables printing the separator line once as soon as the input pauses for at least delay milliseconds. (The delay default is 200 if missing.) Has no effect if pausesep is unset.
Default: enabled, 200ms. - pausesep[=char], ps
Enables printing the separator line once as soon as the input pauses for several milliseconds. The line will consist of this char, repeated until the terminal line is filled. (The char default is "⁻" if missing.) Has no effect if pausewait is unset. - lineprefix=symbol, px
Enables or disables line prefixes for all line types at once. See loglineprefix, metalineprefix, and contlineprefix below.
Default: enabled, "● ". - loglineprefix=symbol, lp
Line prefix string for regular output lines. (See lineprefix.) - contlineprefix=symbol, cp
Line prefix string for continuation lines. (See lineprefix.) - metalineprefix=symbol, mp
Line prefix string for meta lines. (See lineprefix.)
By default, hx produces output as if it had been given this HX_SETTINGS value:
px="● " ps="⁻" pw=200 no48
Control Functions for Character-Imaging I/O Devices, Standard ECMA-48, August 1979.
tail(1), console_codes(4).