Add traces and spans to shell scripts

Usage

Setup

The tracer program has three commands, init, exec, and send.

To begin recording a trace of a set of programs or scripts, first call init supplying honeycomb as the telemetry exporter and providing the name of the dataset these events will be sent to:

$ tracer --telemetry=honeycomb --dataset=builder init

This writes a temporary file (defaulting to .trace) along the following lines:

{
    "start": 1654910414568468483,
    "trace": "fd531dbf96ecdc6ff156482aec6c24f7",
    "parent": "1d1e9d1234ec4649"
}

Run steps

This file is then used by the other two commands exec and send to enable them to know what trace they are a part of. Use exec to execute a step:

$ tracer --telemetry=honeycomb --dataset=builder exec "label-one" command1 ...
$ tracer --telemetry=honeycomb --dataset=builder exec "label-two" command2 ...
$ tracer --telemetry=honeycomb --dataset=builder exec "label-three" command3 ...

By convention the "label" used as the name of the step you are executing is the name of the program, script, or function your are executing, rather than something particularly descriptive.

Finalize

When the sequence of steps is complete, the trace is finished off by creating a root span to be the parent of the previously created leaves and to represent the total duration of the process:

$ tracer --telemetry=honeycomb --dataset=builder send "label"