otel-cli: Usage, Options & Common CI Errors
otel-cli sends OpenTelemetry spans so shell steps appear in your traces.
otel-cli lets a CI pipeline emit OTLP spans for build steps, so a deploy shows up in the same trace as the app. The key is the endpoint and propagating traceparent between steps.
What it does
otel-cli creates OpenTelemetry spans from the command line and sends them over OTLP to a collector. otel-cli exec wraps a command in a span; otel-cli span and span event let you build spans manually and propagate context via traceparent.
Common usage
otel-cli exec --service ci --name "build" -- make build
otel-cli span --service ci --name "deploy" --endpoint http://collector:4317
export TRACEPARENT=$(otel-cli span --service ci --name root --tp-print --tp-export)
otel-cli span event --name "milestone"
otel-cli exec --endpoint http://localhost:4318 --protocol http/protobuf -- ./test.shOptions
| Flag | What it does |
|---|---|
| exec -- <cmd> | Run cmd wrapped in a span |
| --service / --name | Span service name and operation name |
| --endpoint <url> | OTLP endpoint (or $OTEL_EXPORTER_OTLP_ENDPOINT) |
| --protocol grpc|http/protobuf | OTLP transport |
| --tp-print / --tp-export | Print / export traceparent for chaining |
| --otlp-headers "k=v" | Add OTLP headers (e.g. auth) |
Common errors in CI
By default otel-cli fails silently so it never breaks a build - if spans do not show up, the endpoint is wrong or the collector is down; run with --verbose (or --fail) to surface "connection refused" / "context deadline exceeded". A common mistake is port/protocol mismatch: 4317 is gRPC, 4318 is http/protobuf - set --protocol to match. Spans appear disconnected when TRACEPARENT is not propagated between steps; capture it with --tp-export and re-export it in later steps.