gnomon

Run command and display output timestamps

TLDR

Use UNIX (or DOS) pipes to pipe stdout of any command through gnomon

$ [npm test] | gnomon

Show number of seconds since the start of the process

$ [npm test] | gnomon [[-t|--type]] elapsed-total

Show an absolute timestamp in UTC

$ [npm test] | gnomon [[-t|--type]] absolute

Use a high threshold of 0.5 seconds, exceeding which the timestamp will be colored bright red

$ [npm test] | gnomon [[-h|--high]] 0.5

Use a medium threshold of 0.2 seconds, exceeding which the timestamp will be colored bright yellow

$ [npm test] | gnomon [[-m|--medium]] 0.2

SYNOPSIS

gnomon [-m MARKER] [-r RETRIES] [--] [cmd [args ...]]

Or: cmd | gnomon [options]

-m MARKER, --marker=MARKER
    Marker character to prefix lines (default: >)

-r RETRIES, --retries=RETRIES
    Retries on I/O errors before failing (default: 0)

-h, --help
    Display help and exit

--version
    Display version and exit

DESCRIPTION

Gnomon is a lightweight command-line tool designed to add precise, terse timestamps to the output of commands, especially useful in pipelines. When piped input is provided (e.g., cmd | gnomon), it prefixes each line with the elapsed time since gnomon started, in the format <ms> | line. For subsecond precision, it uses <1ms> or >1s.

If invoked with a command (e.g., gnomon cmd args), gnomon runs the command, captures its stdout, annotates it similarly, and prints to stdout while passing stderr through unchanged. At the end, it appends a summary line showing total runtime, e.g., Total: 1.23s.

This makes it ideal for identifying bottlenecks in complex shell pipelines without cluttering output. Written in Python, it's fast and non-intrusive, supporting streaming output. Default marker is >, customizable via options.

EXAMPLES

Pipeline timing: git log --oneline | head -100000 | gnomon
Command timing: gnomon make -j8
Custom marker: cmd | gnomon -m '*'

HISTORY

Created by Will Thames at Yelp in 2016; open-sourced under Apache 2.0. Maintained on GitHub with Python 3 support in later versions (1.0+). Widely adopted for shell debugging.