SET UP OPENTELEMETRY

Prerequisites: Swamp installed.

Enable console tracing for local debugging

Set the OTEL_TRACES_EXPORTER environment variable to console before running a command:

OTEL_TRACES_EXPORTER=console swamp model method run my-greeter execute --input 'run=echo hello'

Span data prints to stdout alongside normal command output. Do not combine OTEL_TRACES_EXPORTER=console with --json in pipelines — trace objects interleave with the JSON output and corrupt parseable output. This exporter is useful for verifying that tracing is working without setting up a collector.

Send traces to a collector

Point Swamp at an OpenTelemetry collector endpoint:

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 swamp model method run my-greeter execute --input 'run=echo hello'

Swamp uses OTLP/HTTP (not gRPC), so the endpoint must be an OTLP/HTTP receiver. Port 4318 is the standard OTLP/HTTP port across collectors (Jaeger, OTel Collector, Grafana Alloy). /v1/traces is appended to the base URL automatically. OTEL_EXPORTER_OTLP_PROTOCOL is not read — the exporter is always HTTP. If your collector uses non-standard ports, check its documentation.

Configure the service name

OTEL_SERVICE_NAME=my-infra swamp model method run my-greeter execute --input 'run=echo hello'

Add vendor-specific headers

For Honeycomb:

OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=your-api-key" \
OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io \
  swamp model method run my-greeter execute --input 'run=echo hello'

For Axiom:

OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token,X-Axiom-Dataset=my-dataset" \
OTEL_EXPORTER_OTLP_ENDPOINT=https://api.axiom.co \
  swamp model method run my-greeter execute --input 'run=echo hello'

Multiple headers are comma-separated in key=value format.

Inject a parent trace context into a run

To correlate a swamp run with an external orchestrator's trace, pass the parent span's traceparent value:

swamp model method run my-greeter execute \
  --traceparent "00-<trace-id>-<span-id>-01" \
  --input 'run=echo hello'

Add --tracestate to carry vendor-specific state:

swamp workflow run deploy-pipeline \
  --traceparent "00-abcd1234abcd1234abcd1234abcd1234-abcd1234abcd1234-01" \
  --tracestate "vendor=value"

The run's spans appear as children of the provided parent in your trace backend. The TRACEPARENT and TRACESTATE environment variables work the same way — the flag takes precedence when both are set.

Disable tracing

To suppress OTel trace export, set the exporter to none:

OTEL_TRACES_EXPORTER=none swamp model method run my-greeter execute --input 'run=echo hello'

SWAMP_NO_TELEMETRY=true controls Swamp's own telemetry but does not suppress OTel trace export.

For the full list of supported environment variables, see the OpenTelemetry reference.