otel-cli is a command-line tool for sending OpenTelemetry traces. It is written in Go and intended to be used in shell scripts and other places where the best option available for sending spans is executing another program.

Since this needs to connect to the OTLP endpoint on each run, it is highly recommended to have a localhost opentelemetry collector running so this doesn't slow down your program too much and you don't spam outbound connections on each command.

The easiest way is a go get:

go get github.com/packethost/otel-cli

Alternatively, clone the repo and build it locally:

git clone [email protected]:packethost/otel-cli.git
cd otel-cli
go build

# run a program inside a span
otel-cli exec --service my-service --name "curl google" curl https://google.com

# otel-cli propagates context via envvars so you can chain it to create child spans
otel-cli exec --kind producer "otel-cli exec --kind consumer sleep 1"

# if a traceparent envvar is set it will be automatically picked up and
# used by span and exec. use --ignore-tp-env to ignore it even when present
export TRACEPARENT=00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01

# create a span with a custom start/end time using either RFC3339,
# same with the nanosecond extension, or Unix epoch, with/without nanos
otel-cli span --start 2021-03-24T07:28:05.12345Z --end 2021-03-24T07:30:08.0001Z
otel-cli span --start 1616620946 --end 1616620950.241980634
# so you can do this:
start=$(date --rfc-3339=ns) # rfc3339 with nanoseconds
some-interesting-program --with-some-options
end=$(date +%s.%N) # Unix epoch with nanoseconds
otel-cli span -n my-script -s some-interesting-program --start $start --end $end

# for advanced cases you can start a span in the background, and
# add events to it, finally closing it later in your script
sockdir=$(mktemp -d)
otel-cli span background \
   --service $0          \
   --name "$0 runtime"   \
   --sockdir $sockdir & # the & is important here, background server will block
sleep 0.1 # give the background server just a few ms to start up
otel-cli span event --name "cool thing" --attrs "foo=bar" --sockdir $sockdir
otel-cli span end --sockdir $sockdir
# or you can kill the background process and it will end the span cleanly
kill %1

Everything is configurable via CLI arguments, and many of those arguments can also be configured via file or environment variables.

We want working on otel-cli to be easy, so we've provided a few different ways to get started. In general, there are three things you need:

• A working Go environment
• A built (or installed) copy of otel-cli itself
• A system to receive/inspect the traces you generate

Providing instructions on getting Go up and running on your machine is out of scope for this README. However, the good news is that it's fairly easy to do! You can follow the normal Installation instructions from the Go project itself.

If you're planning on making changes to otel-cli, we recommend building the project locally: go build

But, if you just want to quickly try out otel-cli, you can also just install it directly: go get github.com/packethost/otel-cli

Here you have one more choice: you can either send traces to a SaaS tracing vendor or other system that you already have, or you can run our docker-compose configuration to launch a local Jaeger system.

If you're not sure what to choose, we recommend trying our Jaeger configuration, which requires no configuration.

Just run docker-compose up from this repository, and you'll get an OpenTelemetry collector and a local Jaeger all-in-one setup ready to go.

The OpenTelemetry collector is listening on localhost:4317, and the Jaeger UI will be running on localhost:16686. Since these are the expected defaults of otel-cli, you can get started with no further configuration:

./otel-cli exec -n my-cool-thing -s interesting-step echo 'hello world'

This trace will be available in the Jaeger UI at localhost:16686.

We've provided Honeycomb and LightStep configurations that you could also use, if you're using one of those vendors today. It's still pretty easy to get started:

# optional: to send data to an an OTLP-enabled tracing vendor, pass in your
# API auth token over an environment variable and modify
# `local/otel-vendor-config.yaml` according to the comments inside
export LIGHTSTEP_TOKEN= # Lightstep API key (otlp/1 in the yaml)
export HONEYCOMB_TEAM=  # Honeycomb API key (otlp/2 in the yaml)
export HONEYCOMB_DATASET=playground # Honeycomb dataset

docker run \
   --env LIGHTSTEP_TOKEN \
   --env HONEYCOMB_TEAM \
   --env HONEYCOMB_DATASET \
   --name otel-collector \
   --net host \
   --volume $(pwd)/local/otel-vendor-config.yaml:/local.yaml \
   public.ecr.aws/aws-observability/aws-otel-collector:latest \
      --config /local.yaml

Then it should just work to run otel-cli:

./otel-cli span -n "testing" -s "my first test span"
# or for quick iterations:
go run . span -n "testing" -s "my first test span"

• add some shell examples for:
  • using bash trap(1p) to send events
• examples for connecting collector to other vendors' OTLP endpoints
• span background doodles: https://gist.github.com/tobert/ceb2cd9b18ab7ab09e1ea7e3bf150d9d

Please file issues and PRs on the GitHub project at https://github.com/packethost/otel-cli

This project is really new and still experiemental, releases are TBD.

Apache 2.0, see LICENSE