Skip to main content
← Back to list
01Issue
FeatureClosedSwamp CLI
Assigneesstack72

Relationships

#1164 Configure the OTLP trace exporter (endpoint/service/headers) in .swamp.yaml, not only via OTEL_ env vars

Opened by magistr · 7/15/2026

Today the OTLP distributed-tracing exporter is enabled ONLY via the OTEL_EXPORTER_OTLP_ENDPOINT environment variable — otel_init.ts reads Deno.env directly. There is no repo-level (.swamp.yaml) way to turn tracing on, so every user must hack their shell rc / direnv to trace the CLI.

Three sharp edges make this confusing:

  1. .swamp.yaml ALREADY has a telemetryEndpoint field — but it drives the SEPARATE product usage-telemetry system (HttpTelemetrySender -> https://telemetry.swamp-club.com), NOT OTLP tracing. A user reasonably expects telemetryEndpoint to control tracing; it silently does not.
  2. swamp reads the repo .env for datastore passwordEnv resolution, but those keys are not loaded into the process env, so putting OTEL_EXPORTER_OTLP_ENDPOINT in .env does nothing for tracing.
  3. So the only lever is a real env var, which cannot be committed with the repo.

Request: support an OTLP tracing block in .swamp.yaml, symmetrical to how datastore is already configured there. e.g.

tracing:
  otlpEndpoint: http://[HOST-1]:4318   # HTTP base; /v1/traces appended
  serviceName: swamp                             # optional, defaults to "swamp"
  headers:                                       # optional -> OTEL_EXPORTER_OTLP_HEADERS
    x-api-key: ...
  disabled: false

Precedence: explicit OTEL_ env vars > .swamp.yaml tracing block > off. This lets a repo opt into tracing to a self-hosted collector without polluting the global shell.

Use case: piping swamp CLI traces + Claude Code telemetry into a self-hosted OpenTelemetry Collector -> ClickHouse. Related doc bug: #1163.

02Bog Flow
✓OPEN✓TRIAGED○IN PROGRESS◉CLOSED+ 1 MOREASSIGNED+ 2 MOREREVIEW

Closed

7/16/2026, 12:56:07 AM

No activity in this phase yet.

03Sludge Pulse
stack72 assigned stack727/15/2026, 8:54:33 PM
Editable. Press Enter to edit.

stack72 commented 7/16/2026, 12:56:05 AM

Thanks for the detailed write-up @magistr — the confusion between telemetryEndpoint (product analytics) and OTLP tracing is a real paper cut, and we agree that's worth addressing in documentation (see #1163).

For the .swamp.yaml tracing block itself: we looked into this and the core challenge is that OTLP tracing initializes in main.ts before CLI argument parsing and before .swamp.yaml is loaded. Moving tracing initialization later would lose the initial startup traces, which are some of the most valuable for debugging. Reading .swamp.yaml earlier introduces a second marker-read path before the CLI is set up, which is a fragile change we're not comfortable making — any failure there (permissions, malformed YAML, symlinks) would block the entire CLI before it even starts.

The two-phase approach (start from env vars, reconfigure after marker load) adds significant complexity to the tracing lifecycle, and OTel providers aren't designed to be reconfigured mid-flight.

Given all of that, this isn't the right time for us to take on a rewrite of the initialization flow for what is ultimately a convenience over the standard OTEL_* environment variables. The env vars work well with direnv (.envrc) for per-repo tracing config that lives alongside the repo without changing swamp's startup path.

We're going to close this for now, but if the init flow changes for other reasons in the future, we'd revisit this idea then.

Sign in to post a ripple.