otel -- Treeship -- Treeship

Treeship can export every artifact as an OpenTelemetry (OTLP) span, letting you visualize agent workflows in any observability tool that speaks OTLP.

Feature flag

OpenTelemetry support is behind a compile-time feature flag to keep the default binary lean. The default treeship binary distributed via npm install -g treeship and curl -fsSL treeship.dev/install | sh does NOT include OTel; you have to build the binary yourself with the flag enabled.

git clone https://github.com/zerkerlabs/treeship && cd treeship
cargo build --release --bin treeship --features otel
# the OTel-enabled binary is at ./target/release/treeship

Without the feature flag, all treeship otel commands print a rebuild hint:

OpenTelemetry support is not compiled in.
Rebuild from source with: cargo build --release --bin treeship --features otel

Do NOT use cargo install treeship-cli from crates.io -- that crate is orphaned at v0.4.0. The CLI ships exclusively via the npm wrapper (npm install -g treeship) and the treeship.dev/install script, which fetch a prebuilt platform binary. To get a Rust toolchain build, clone the repo and cargo build as above.

Commands

treeship otel test

Verify OTLP connectivity by sending a test span to the configured endpoint.

treeship otel test

→ sending test span to http://localhost:4318...
[pass] span accepted
→ treeship otel status

treeship otel status

Show the current OpenTelemetry configuration.

treeship otel status

OTel export:   enabled
Endpoint:      http://localhost:4318
Service name:  treeship
Auth:          (none)
Spans sent:    42
Last export:   2026-03-31T14:20:03Z

treeship otel export <id>

Export a single artifact as an OTLP span.

treeship otel export art_f8e2a1b3c4d5e6f7

→ exported art_f8e2a1b3c4d5e6f7 as span
  trace_id:  4bf92f3577b34da6a3ce929d0e0e4736
  span_id:   00f067aa0ba902b7
→ treeship otel status

treeship otel enable

Enable automatic span export. When enabled, treeship wrap and treeship session close automatically export spans.

treeship otel enable

treeship otel disable

Disable automatic span export.

treeship otel disable

Auto-export behavior

When OTel export is enabled:

treeship wrap -- <cmd> exports a span after the command finishes
treeship session close exports spans for all artifacts in the session
Each span includes all artifact fields as span attributes

Environment variables

Variable	Description	Default
`TREESHIP_OTEL_ENDPOINT`	OTLP HTTP endpoint (must support `/v1/traces`)	`http://localhost:4318`
`TREESHIP_OTEL_AUTH`	Bearer token for authenticated endpoints	(none)
`TREESHIP_OTEL_SERVICE`	Service name attached to all spans	`treeship`
`TREESHIP_OTEL_ENABLED`	Set to `1` to enable, `0` to disable	`0`

Span attributes

Every exported span includes these attributes:

Attribute	Example
`treeship.artifact_id`	`art_f8e2a1b3c4d5e6f7`
`treeship.actor`	`agent://ci-runner`
`treeship.type`	`treeship/action/v1`
`treeship.action`	`npm test`
`treeship.exit_code`	`0`
`treeship.elapsed_ms`	`3204`
`treeship.output_digest`	`sha256:a1b2c3d4...`
`treeship.parent_id`	`art_c4d5e6f7a1b2c3d4`
`treeship.verify_url`	`https://treeship.dev/verify/art_f8e2a1b3c4d5e6f7`
`treeship.session_id`	`sess_20260331_142000`

Compatible backends

Works with any backend that accepts OTLP over HTTP:

Jaeger (local development)
Honeycomb
Datadog
Langfuse (LLM observability)
Arize Phoenix (LLM tracing)
Grafana Tempo

Quick start with local Jaeger

# Start Jaeger with OTLP support
docker run -d -p 4318:4318 -p 16686:16686 jaegertracing/all-in-one

# Point Treeship at it
export TREESHIP_OTEL_ENDPOINT=http://localhost:4318

# Verify connectivity
treeship otel test

# Run a command -- span is exported automatically
treeship otel enable
treeship wrap -- npm test

# Open Jaeger UI to see the span
# http://localhost:16686

For Honeycomb or Datadog, set TREESHIP_OTEL_AUTH to your API key and TREESHIP_OTEL_ENDPOINT to the vendor's OTLP ingest URL.

otel

On this page