Observability

SwarmClaw now supports opt-in OpenTelemetry trace export over OTLP. This is intentionally a foundation release: it emits traces to your existing backend, but it does not yet include a first-class in-app trace viewer.

What Gets Traced

When OTLP export is enabled, SwarmClaw emits spans around:

  • full chat turns
  • agentic chat streaming runs
  • direct provider/model streaming calls
  • protocol / structured-session runs
  • tool execution

The spans are designed to answer practical operator questions such as:

  • which chats are slow
  • which tools are failing
  • which protocol runs are stuck
  • whether a hosted deployment is hitting the model backend or serving cached results

Environment Variables

Enable OTLP export with environment variables:

OTEL_ENABLED=true
OTEL_SERVICE_NAME=swarmclaw
OTEL_EXPORTER_OTLP_ENDPOINT=https://your-collector:4318
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer your-token

If your collector expects a trace-specific endpoint, use:

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://your-collector:4318/v1/traces

When OTEL_EXPORTER_OTLP_TRACES_ENDPOINT is not set, SwarmClaw appends /v1/traces to OTEL_EXPORTER_OTLP_ENDPOINT.

Supported Backends

Anything that accepts standard OTLP traces should work. Common examples:

  • Langfuse
  • Jaeger
  • Grafana Alloy / Tempo
  • Datadog via OTLP intake
  • a standalone OpenTelemetry Collector forwarding elsewhere

Deployment Notes

  • The feature is off by default.
  • Hosted deployments should set OTLP env vars in the platform dashboard or secret manager, not in a checked-in file.
  • If OTEL_ENABLED=true is set without a valid OTLP endpoint, tracing stays effectively disabled.
  • Health checks continue to use /api/healthz; trace export does not affect the public liveness path.

Suggested First Step

For a new hosted deployment, start with:

  1. Deploy SwarmClaw.
  2. Confirm /api/healthz is healthy.
  3. Enable OTLP export.
  4. Trigger a chat turn and one tool call.
  5. Check that spans arrive in your collector before expanding rollout.