by sgreben

sgreben / tj

stdin line timestamps. single binary, no dependencies. osx & linux & windows. plays well with jq.

205 Stars 2 Forks Last release: over 2 years ago (7.0.0) 37 Commits 21 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

tj - stdin line timestamps, JSON-friendly

timestamps lines read from standard input.

Get it

Using go get:

go get -u

Or download the binary from the releases page:

# Linux
curl -L | tar xz


curl -L | tar xz


curl -LO unzip

Also available as a docker image:

docker pull

Use it

reads from stdin and writes to stdout.
Usage of tj:
  -template string
        either a go template ( or one of the predefined template names
  -time-format string
        either a go time format string or one of the predefined format names (
  -time-zone string
        time zone to use (or "Local") (default "UTC")
  -match-regex string
        a regex pattern. if given, only tokens matching it (re)start the stopwatch
  -match-template string
        go template, used to extract text used for -match-regex
  -match-condition string
        go template. if given, only tokens that result in 'true' (re)start the stopwatch
        buffer lines between matches of -match-regex / -match-condition, copy delta values from final line to buffered lines
  -match string
        alias for -match-template
  -condition string
        alias for -match-condition
  -regex string
        alias for -match-regex
        parse a sequence of JSON objects from stdin
  -scale string
        either a sequence of hex colors or one of the predefined color scale names (colors go from fast to slow)
      (default "BlueToRed")
  -scale-fast duration
        the lower bound for the color scale (default 100ms)
  -scale-slow duration
        the upper bound for the color scale (default 2s)
        use linear scale (default true)
        use cubic scale
        use cubic root scale
        use quadratic scale
        use quadratic root scale
        print version and exit

JSON output

The default output format is JSON, one object per line:

$ (echo Hello; echo World) | tj

Time format

You can set the format of the

field using the
$ (echo Hello; echo World) | tj -time-format Kitchen

The constant names from pkg/time as well as regular go time layouts are valid values for


| Name | Format | |------------|-------------------------------------| | ANSIC |

Mon Jan _2 15:04:05 2006
| | Kitchen |
| | ISO8601 |
| | RFC1123 |
Mon, 02 Jan 2006 15:04:05 MST
| | RFC1123Z |
Mon, 02 Jan 2006 15:04:05 -0700
| | RFC3339 |
| | RFC3339Nano|
| RFC822 |
02 Jan 06 15:04 MST
| | RFC822Z |
02 Jan 06 15:04 -0700
| | RFC850 |
Monday, 02-Jan-06 15:04:05 MST
| | RubyDate |
Mon Jan 02 15:04:05 -0700 2006
| | Stamp |
Jan _2 15:04:05
| | StampMicro |
Jan _2 15:04:05.000000
| | StampMilli |
Jan _2 15:04:05.000
| | StampNano |
Jan _2 15:04:05.000000000
| | UnixDate |
Mon Jan _2 15:04:05 MST 2006

Template output

You can also specify an output template using the

parameter and go template syntax:
$ (echo Hello; echo World) | tj -template '{{ .I }} {{.TimeSecs}} {{.Text}}'
0 1516649679 Hello
1 1516649679 World

The fields available to the template are specified in the


Some templates are pre-defined and can be used via

-template NAME

| Name | Template | |-----------------|--------------------------------------------------| | Color |

{{color .}}█{{reset}} {{.Text}}
| | ColorText |
{{color .}}{{.Text}}{{reset}}
| | Delta |
{{.Delta}} {{.Text}}
| | DeltaColor |
{{.Delta}} {{color .}}█{{reset}} {{.Text}}
| | DeltaNanos |
{{.DeltaNanos}} {{.Text}}
| | Text |
| | Time |
{{.TimeString}} {{.Text}}
| | TimeColor |
{{.TimeString}} {{color .}}█{{reset}} {{.Text}}
| | TimeDelta |
{{.TimeString}} +{{.Delta}} {{.Text}}
| | TimeDeltaNanos |
{{.TimeString}} +{{.DeltaNanos}} {{.Text}}

Color output

To help identify durations at a glance,

maps durations to a color scale. The pre-defined templates
demonstrate this:
$ (echo fast; 
   sleep 1; 
   echo slower; 
   sleep 1.5; 
   echo slow; 
   sleep 2; 
   echo slowest) | tj -template Color

Color output

The terminal foreground color can be set by using

{{color .}}
in the output template. The default terminal color can be restored using

The color scale can be set using the parameters

, and
  • The
    parameter defines the colors used in the scale.
  • The
    parameters define the boundaries of the scale: durations shorter than the value of
    are mapped to the leftmost color, durations longer than the value of
    are mapped to the rightmost color.

The scale is linear by default, but can be transformed:

  • -scale-sqr
    yields a quadratic (root) scale
  • -scale-cube
    yields a cubic (root) scale

There are several pre-defined color scales:

| Name | Scale | |---------------------|----------------------- | | BlackToPurple |

#000 -> #F700FF
| | BlackToRed |
#000 -> #F00
| | BlueToRed |
#00F -> #F00
| | CyanToRed |
#0FF -> #F00
| | GreenToRed |
#0F0 -> #F00
| | GreenToGreenToRed |
#0F0 -> #0F0 -> #F00
| | WhiteToPurple |
#FFF -> #F700FF
| | WhiteToRed |
#FFF -> #F00
| | WhiteToBlueToRed |
#FFF -> #00F -> #F00

You can also provide your own color scale using the same syntax as the pre-defined ones.

JSON input


, you can tell
to parse stdin as a sequence of JSON objects. The parsed object can be referred to via
, like this:
$ echo '{"hello": "World"}' | tj -read-json -template "{{.TimeString}} {{.Object.hello}}"
2018-01-25T21:55:06+01:00 World

The exact JSON string that was parsed can be recovered using

$ echo '{"hello"   :    "World"} {   }' | tj -read-json -template "{{.TimeString}} {{.Text}}"
2018-01-25T21:55:06+01:00 {"hello"   :    "World"}
2018-01-25T21:55:06+01:00 {   }

Stopwatch regex

Sometimes you need to measure the duration between certain tokens in the input.

To help with this,

can match each line against a regular expression and only reset the stopwatch (
) when a line matches. The regular expression can be specified via the
) parameter.

Stopwatch regex template

When using

, you can also specify a template
) to extract text from the current token. The output of this template is matched against the stopwatch regex.

This allows you to use only specific fields of JSON objects as stopwatch reset triggers. For example:

$ (echo {}; sleep 1; echo {}; sleep 1; echo '{"reset": "yes"}'; echo {}) | 
    tj -read-json -match .reset -regex yes -template "{{.I}} {{.DeltaNanos}}"
0 14374
1 1005916918
2 2017292187
3 79099

The output of the match template is stored in the field

of the
$ echo '{"message":"hello"}' | tj -read-json -match-template .message -template "{{.TimeString}} {{.MatchText}}"
2018-01-25T22:20:59+01:00 hello

Stopwatch condition

Additionally to

, you can specify a
go template. If this template produces the literal string
, the stopwatch is reset - "matches" of the
are treated like matches of the


Finding the slowest step in a

docker build
$ cat Dockerfile
FROM alpine
RUN echo About to be slow...
RUN sleep 10
RUN echo Done being slow
$ docker build . |
    tj -regex ^Step |
    jq -s 'max_by(.deltaNanos) | {step:.start.text,}'
{"step":"Step 3/4 : RUN sleep 10","duration":"10.602026127s"}

Alternatively, using color output and buffering:

$ docker build . |
    tj -regex ^Step -match-buffer -template Color -scale-cube

Docker build with color output


Feel free to leave a comment or create an issue.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.