langfuse-openclaw-exporter is a relay that reads OpenClaw session logs and pushes structured events to Langfuse through the public ingestion API.

For agent operations, we need conversation-native observability:

• one session with many turn-level traces
• each trace with multiple child spans (generation, tool calls, tool results)
• stable correlation across retries, partial tool outputs, and final assistant responses

This hierarchy is what makes debugging, latency analysis, and cost attribution practical at the conversation-turn level.

OpenClaw diagnostics-otel is useful and can export OpenTelemetry signals (metrics, traces, logs) over OTLP/HTTP.

However, for this project we need deterministic reconstruction of OpenClaw conversation turns and tool-call lineage as Langfuse-native objects. In practice, we use session logs because they contain the exact message stream (user, assistant, toolCall, toolResult) required to rebuild:

• a single session with multiple turn traces
• per-trace span trees aligned to real tool lifecycle
• trace input/output payloads exactly as seen by the agent runtime

So this exporter is not an anti-OTel statement. It is a data-model bridge for a specific requirement: preserving OpenClaw conversation semantics in Langfuse.

The OpenClaw OTel diagnostics effort (including diagnostics-otel, see PR context: openclaw/openclaw#12897) improves telemetry export, but this project still fills a different gap:

• turn-aware session reconstruction
• stable conversation-centric trace grouping
• Langfuse-oriented generation/span mapping from raw session events

• watches OpenClaw session files from the sessions index
• persists per-file read offsets (supports backfill mode)
• maps session events into Langfuse ingestion events (trace-create, span-create, generation-create, span-update)
• batches and sends events to Langfuse

• LANGFUSE_RELAY_STATE_PATH
• OPENCLAW_SESSIONS_INDEX_PATH
• LANGFUSE_BASE_URL
• LANGFUSE_PUBLIC_KEY
• LANGFUSE_SECRET_KEY
• LANGFUSE_RELAY_POLL_SEC
• LANGFUSE_RELAY_BACKFILL

• OpenClaw logging and diagnostics docs: https://docs.openclaw.ai/logging
• Example integration guide discussing diagnostics-otel: https://signoz.io/blog/monitoring-openclaw-with-opentelemetry/
• OpenClaw PR context mentioned above: openclaw/openclaw#12897