trufflehunter

log file searching utility

USAGE:
    hun [FLAGS] [OPTIONS] [ARGS]

FLAGS:
    -h, --help         Prints help information
        --long-help    Long help information explaining formats and time expressions
    -V, --version      Prints version information
        --verbose      Provide the precise time range and line numbers

OPTIONS:
    -e, --end-line <n>      The last line to search to
    -f, --format <rx>       The time stamp format
    -s, --start-line <n>    The first line to search from

ARGS:
    <LOG>        The log file to search in
    <WHEN>...    The period of time to search for events in

Trufflehunter (hun) is a tool for quickly extracting lines from a log file within a specified time range. Its required arguments are a log file name and a time expression.

Examples

> hun log.txt from 3 am today until 3:15
2019-01-12 3:00:01 -- tomorrow and tomorrow and tomorrow
sometimes there's garbage between timestamps
2019-01-12 3:05:13 -- creeps in this petty pace from day to day
2019-01-12 3:06:00 -- to the last syllable of recorded time
[exit stage left pursued by bear]
2019-01-12 3:10:23 -- and all our yesterdays have lighted fools
2019-01-12 3:14:59 -- the way to dusty death

> hun --verbose log.txt from 3 am today until 3:06
lines 12345 - 12349
2019-01-12 3:00:01 -- tomorrow and tomorrow and tomorrow
sometimes there's garbage between timestamps
2019-01-12 3:05:13 -- creeps in this petty pace from day to day
2019-01-12 3:06:00 -- to the last syllable of recorded time
[exit stage left pursued by bear]

Time Expressions

Trufflehunter uses the two_timer crate to parse time expressions. The range of time expressions it will understand would be somewhat arduous to enumerate. In general they fit one of these patterns

<time>
from <time a> to <time b>
<period> around/before/after <time>

The two_timer parser is meant to emulate the semantics of English temporal expressions. You can experiment to see what it will accept. When in doubt, it doesn't hurt to be be specific. E.g.,

5 minutes before and after 3:13:45 PM on June 5, 1910

Timestamp Formats

A time stamp format must be a string that can compile to a regular expression with named capturing groups for "year", "month", "day", "minute", "hour", and "second". No named captures are required, but a format without any captures won't do a very good job finding timestamps. Be aware that you cannot reuse a named capture name in Rust regexes. The expression

(?<foo>f) (?<bar>b) | (?<bar>b) (?<foo>f)

is ill-formed.

The default format is

(?:[^\d'"`>]|^)(?P<year>[0-9]{4})\D{1,2}(?P<month>[0-9]{1,2})\D{1,2}(?P<day>[0-9]{1,2})\D{1,2}(?P<hour>[0-9]{1,2})\D{1,2}(?P<minute>[0-9]{1,2})\D{1,2}(?P<second>[0-9]{1,2})(?:[^\d'"`<]|$)

This is meant to match most log timestamps without matching quoted timestamps in logged SQL or a data serialization language such as JSON or XML.

This is obviously quite a bit to type on the command line. Most often the default pattern will match a log file's timestamps.

If a line contains no timestamp it will be treated as having the same timestamp as closest line before it with a timestamp.

Start and End Lines

The --start-line and --end-line options allow one to work around misordered log lines or failures of the time format. If trufflehunter errors out because it encounters misordered, or "misordered", lines, you may be able to work around these rough patches by specifying a sub-range of lines to search in.

The Name

The truffles trufflehunter hunts are the desired periods in logs. Trufflehunter is also the name of a talking badger in the Chronicles of Narnia.