CI command wrapper that generates and exports traces in OpenTelemetry format
MIT License
OpenTelemetry tracing for CI pipelines
Traci is a CI command wrapper that generates and exports traces in OpenTelemetry format. It uses the OpenTelemetry SDK under the hood and can be configured to send traces to any OpenTelemetry-compatible backend.
Traci supports CI detection for the following CI platforms:
If you don't see your CI provider, open an issue or submit a PR!
go install github.com/nextrevision/traci@latest
traci exec echo "hello world"
Traci detects the CI environment and automatically generates trace and span IDs for each command. It will also detect
the OTel endpoint using the OTEL_EXPORTER_OTLP_ENDPOINT
environment variable.
export OTEL_EXPORTER_OTLP_ENDPOINT=https://jaeger.mycompany:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
traci exec echo "hello jaeger"
Traci supports configuration via environment variables in both exec
and execf
commands. The execf
command also
supports CLI flags. CLI flags take precedence over environment variables.
Environment Variable |
execf CLI Flag |
Description |
---|---|---|
TRACI_SERVICE_NAME |
--service-name, -n |
The name of the service |
TRACI_SPAN_NAME |
--span-name, -s |
The name of the span |
TRACI_TRACE_BOUNDARY |
--trace-boundary, -t |
The scope of the generated trace. Can be pipeline or job
|
TRACI_TAG_COMMAND_ARGS |
--tag-command-args |
Include command args as tags in the span |
Traci uses the OpenTelemetry Go SDK under the hood and can be configured using the same environment variables. See the OpenTelemetry General SDK documentation for a full list of available configuration options. Below are some of the more common options.
Environment Variable | Description | Example Value |
---|---|---|
OTEL_EXPORTER_OTLP_ENDPOINT |
The OTel endpoint to send traces to. | https://jaeger.mycompany:4317 |
OTEL_EXPORTER_OTLP_PROTOCOL |
The OTel protocol to use. Can be grpc or http . |
grpc |
OTEL_RESOURCE_ATTRIBUTES |
Resource attributes to include in the trace. | service.namespace=tutorial,service.version=1.0 |
OTEL_EXPORTER_OTLP_HEADERS |
Headers to include in the request. | x-something=foo,x-something-else=bar |
Traci detects CI providers by environment variables. Most CI providers offer a consistent, unique identifier per "pipeline" or "workflow". Traci uses these identifiers to generate repeatable trace IDs without the need for manual propagation via some other means. This means commands in different jobs/steps of a pipeline/workflow will associate with the same trace ID automatically.
Traci can use the CI deterministic trace ID to determine the trace boundary. The trace boundary determines how far a
trace will propagate. For example, if the trace boundary is set to pipeline
, the trace will include all wrapped commands
in every job in a pipeline. If the trace boundary is set to job
, the trace will only include all commands in the job.
The default trace boundary is pipeline
.
Pipeline
is a generic term to describe a grouping of jobs. A pipeline includes the following CI vendor concepts:
Job
is a generic term to describe a grouping of commands. A job includes the following CI vendor concepts:
TRACEPARENT
Environment VariableTraci supports propagating trace context between commands using the TRACEPARENT
environment variables. If a valid
trace context is set in the TRACEPARENT
variable, traci will use that to determine the parent trace and span ids. The
exec
and execf
commands will also inject a W3C Trace Context compatible
TRACEPARENT
variable into the environment of the command being executed. This allows traces to be propagated between
commands by traci or other tools that look for that variable. For example:
traci exec /bin/sh -c 'traci exec /bin/sh -c "echo $TRACEPARENT"'
traci exec
The traci exec
commands does not support any traci CLI options opting to pass all args to the command being executed. It
can be configured via environment variables, however. For example:
export TRACI_SPAN_NAME=foo
traci exec echo "hello world"
# or
TRACI_SPAN_NAME=bar traci exec echo "hello world"
traci execf
The traci execf
command does parse traci CLI options and requires the use of the bash end of command-line options --
separator to pass args to the command being executed. This command can also be configured via environment variables. For
example:
traci execf --span-name foo -- echo "hello world"
stages:
- test
- build
- deploy
variables:
OTEL_EXPORTER_OTLP_ENDPOINT: https://jaeger:4317
OTEL_EXPORTER_OTLP_PROTOCOL: grpc
default:
image: alpine
before_script:
- wget -O /tmp/traci.tgz https://github.com/nextrevision/traci/releases/download/v0.3.2/traci_0.3.2_linux_amd64.tar.gz && tar -C /usr/local/bin -xzf /tmp/traci.tgz traci
- traci detect
test:
stage: test
script:
- traci execf --tag-command-args -- /bin/sh -c 'echo $TRACEPARENT'
- traci exec sleep 1
build:
stage: build
script:
- traci exec env
- traci exec sleep 2
deploy:
stage: deploy
script:
- traci exec /bin/sh -c 'traci exec /bin/sh -c "echo $TRACEPARENT"'
- traci exec sleep 3
Use traci with other CI instrumentations:
Traci is heavily inspired by the following projects: