Set up Langfuse
Configure a Langfuse destination, understand exporter coverage, and check whether traces arrive.
In this guide
Observability configures exporter settings for supported agent launches. It is off by default, separate from product analytics, and is not a full token profiler. Configuring a destination does not prove that a harness exports traces or that Langfuse has ingested them.
Choose a destination
Open Settings → Observability. The switch is always visible. Set up a backend before turning it on.
Set up local Langfuse uses Langfuse on this computer. Connect existing backend accepts a local, self-hosted, or cloud Langfuse project. Langfuse is the supported destination; compatibility with other OTLP backends is not verified.
Setup configures export. Native harness fields and backend ingestion require separate evidence.
Diagram by AgentGridSet up locally
- Check Docker prerequisites. AgentGrid distinguishes a missing CLI, an unusable CLI, missing or unusable Compose, an unreachable daemon, and ready prerequisites. It does not install or start Docker.
- Choose Set up local Langfuse. Setup downloads the stack, starts containers, and provisions a project, login, and API keys under app user data. It also installs third-party OpenCode and Pi tracing extensions when those harnesses are present. Failed extension setup is shown even when Docker is healthy.
- Open Local sign-in to reveal the generated login, then use Open dashboard.
- Enable Observability separately when you want new sessions to export. Setup saves connection details without enabling export.
On macOS, follow OrbStack setup, or use your existing Docker runtime. On Windows, use Docker Desktop with WSL2 and Linux containers. On Linux, install Docker Engine and the Compose plugin.
An unreachable daemon can mean a stopped runtime, unavailable Docker context, or socket permissions. Check again reruns read-only probes. Ready prerequisites do not establish Langfuse health. The default dashboard is http://localhost:3100; the exporter base endpoint is http://localhost:3100/api/public/otel.
Connect an existing project
Choose Connect existing backend, enter the Langfuse OTLP endpoint and project keys, then enable Observability separately. Off-device destinations show a warning: supported exporters may send prompts, tool content, and token usage to that destination.
Expand Connection settings to change destination, credentials, or content capture. Changes save automatically. A usable stored secret shows Secret key saved. Replace opens a blank input; Cancel keeps the stored secret. The UI never pre-fills the decrypted secret. Saving is not a connection test.
Include prompts and tool parameters is on by default, but export remains opt-in. Content-off configures supported content gates; it is not a universal redaction guarantee for third-party exporters or independently configured telemetry. Start a new session after changing settings. Existing processes retain their launch configuration.
Understand coverage
This table describes configuration coverage, not freshly measured real-harness export or Langfuse ingestion.
| Harness / launch mode | Setup path | Evidence and limits |
|---|---|---|
| Claude GUI masters, Coordinator, SDK workers/prewarm, PTY workers and recognized master PTYs | Native telemetry environment | Wiring is tested. Native traces depend on installed Claude version. Claude 2.1.283 emitted enhanced beta traces in an isolated synthetic-model test, and Langfuse 4.6.0 ingested them. This is not verification of every launch route or a real provider response. Bare token attributes were retained but did not populate normalized Langfuse usage. |
| Codex GUI masters/Coordinator/workers and recognized master PTYs | Per-process config overrides and environment headers | Preserves CODEX_HOME and session location without enabling export in standalone Codex sessions. Codex 0.157.1 app-server used these production helpers to send native traces directly to authenticated Langfuse 4.6.0, without proxy-added authorization, in an isolated synthetic-model test. Langfuse retained exact thread/turn identifiers after native session resume. This does not verify every launch route, normalized token usage, or tool/compaction contents. |
| OpenCode GUI masters/Coordinator/workers | Host environment reaches server and run client | Requires a compatible @devtheops/opencode-plugin-otel installation. Setup tests are not plugin-export proof. |
| OpenCode recognized PTYs; Pi GUI/worker/recognized PTYs | Environment plus extension | Pi setup uses pi-otel-telemetry. Fields, content gates, and ingestion remain unverified for installed versions. |
| Cursor, Devin ACP, Grok, Kimi, Antigravity GUI/worker paths and recognized PTYs | Host environment / recognized-command environment | Environment delivery does not establish trace support. Treat tracing as unsupported/unverified here. |
| Hermes GUI/worker/PTY paths; naming/helper subprocesses | No AgentGrid OTEL integration | Not covered. Hermes was added on main; its launcher has no observability environment hook. |
| Ordinary shell panes | No AgentGrid observability overlay | Existing user-provided environment is left alone. |
| Standalone or remote daemon hosts | Host-dependent | Electron-encrypted keys cannot be decrypted in standalone Node mode. Authenticated export is not verified. |
The setup uses OTLP HTTP/protobuf with traces enabled and logs/metrics disabled. Some upstream usage or correlation fields may exist only in logs or metrics and will not arrive through this configuration.
Know the limits
A small trace icon beside the processed-token footer resolves supported turns to actual Langfuse traces. Claude uses persisted native session/request IDs; Codex uses the native thread/turn IDs emitted on its turn span. Open turn trace sends the validated exact trace URL to your system browser. Browser preferences control whether it appears in a new tab or window. Links survive native session-history reload; they do not substitute a session dashboard or guess a trace ID. Other harnesses, missing IDs, and export off have disabled states. Lookup runs on click; pending or failed lookups can be retried. Ready results are cached briefly per destination and credentials. Claude links identify the interaction containing the last reported request; multiple interactions and subagent traces are not aggregated.
The isolated Claude test retained content as raw metadata attributes; Langfuse Input/Output and normalized usage remained empty. Codex retained raw input/output/cache/reasoning counters in turn-span metadata, but these did not populate normalized usage. No prompt content was observed in the isolated Codex trace batches. They do not establish rendered prompt/tool timelines or token aggregation.
This is not a context profiler. Token fields, reasoning, tool content, and compaction events depend on the harness and exporter version. Missing fields mean unavailable, not zero; cache and reasoning counts may be subsets of input/output rather than additional tokens.
Loopback regression tests use fake credentials and synthetic fixtures. They verify transport receipt and fixture content/export gates, not real-harness export or Langfuse ingestion.
Check status and troubleshoot
Open dashboard opens the destination. Start and Stop, inside Connection settings, control the managed local stack without changing export preferences; Start does not install extensions. Troubleshoot appears when a prerequisite or setup error needs attention. It shows checks, available setup details, and extension results.
Local containers running means at least one Compose service is running, not that every service is healthy. Trace reception not checked remains explicit: setup status does not measure receipt. The separate turn-link lookup checks only the matching native request; it does not certify complete exporter coverage.
To validate a real installation, start a new supported session with non-sensitive test content, then inspect the backend for matching native session/request IDs and timestamps. HTTP success alone does not prove a generation appears in Langfuse. Check retries, duplicate usage, and resume continuity before relying on totals.
Credentials use Electron safe storage. Codex receives authentication through its process environment, never command arguments. Local setup writes bootstrap credentials under user data. Protect those files. The managed Compose file is pinned to revision b53d37e14e4cadcd587160680bbbdcea7316eaf8. Each installation uses a separate Compose project derived from its canonical installation path; it never adopts the default langfuse project. Moving the installation changes that identity. A port already in use causes startup to fail rather than reuse another stack. Only the web dashboard and object-store endpoints publish loopback ports; database, Redis, ClickHouse, and worker services stay on the Compose network. Service passwords, encryption key, and signing secrets are randomly generated and persisted in owner-readable files. Container image tags still follow that upstream file; this is not a claim of digest-pinned images or a tested live stack. Older installs without the security record are blocked from starting and need a deliberate migration; their data is not erased or credentials silently rotated.
Saving Observability settings removes a legacy AgentGrid-marked Codex block, if present, from the actual CODEX_HOME configuration; unrelated bytes are preserved. New launches use scoped overrides and do not write that file. When disabled, AgentGrid leaves independently configured exporter environment variables unchanged and adds no export credentials. When enabled, AgentGrid's selected destination and content gates take precedence for supported new launches. Already-running sessions retain their original configuration.