Observability

Taxiway's observability stack is the optional Langfuse runtime used to store and inspect model traces. It is separate from lab gateways:

• Observability stack: Langfuse web, Langfuse worker, Postgres, ClickHouse, Redis, and MinIO.
• Gateway path: the shared Caddy proxy plus one LiteLLM sidecar per lab.

The observability stack does not proxy model traffic. Lab gateways can export LiteLLM traces to Langfuse when observability is running, but they can also run without Langfuse.

For the gateway side, see Gateway.

Prerequisites

• docker on PATH and a reachable Docker daemon

Langfuse runs on Docker regardless of the selected lab driver. Lima-backed labs still use Docker for host-local services such as the shared proxy, lab gateways, and observability.

Quick Start

Start the full local runtime:

taxiway init
taxiway observe open

taxiway init starts the shared proxy and the Langfuse observability stack. It does not create a lab and does not start a lab LiteLLM gateway.

If you only want Langfuse and the proxy:

taxiway observe up
taxiway observe open

To generate traces, start or refresh a lab gateway separately:

taxiway gateway <lab>

Then run model traffic through the lab gateway. Successful LiteLLM calls appear in Langfuse when the lab has generated Langfuse keys.

Access

Langfuse is exposed through the shared Taxiway proxy:

http://langfuse.localhost:<proxy-port>

Use the live command output instead of guessing the port:

taxiway access
taxiway status

When Taxiway is installed, the default proxy endpoint is usually:

http://langfuse.localhost:4000

Commands

Gateway commands such as taxiway gateway <lab>, taxiway up <lab>, and taxiway run <lab> are documented in Gateway.

Runtime State

Installed runtimes store mutable observability state under:

~/.taxiway/observability

The generated observability environment file is:

~/.taxiway/observability/.env

The Langfuse Compose file is a runtime asset under:

~/.taxiway/runtime/infra/observability/langfuse.compose.yml

The shared proxy state is separate:

~/.taxiway/proxy

When running from a source checkout, these paths are redirected into the checkout and the Compose project and proxy container are namespaced per checkout — see Development.

Relationship To Gateways

Langfuse receives traces from LiteLLM. It does not manage provider credentials, model routing, or lab gateway keys.

The lab gateway phase is responsible for:

• generating the lab-specific LiteLLM API key;
• creating the lab LiteLLM sidecar and gateway Postgres database;
• registering the <lab>.litellm.localhost route in the shared proxy;
• generating local Langfuse ingestion keys for that lab when observability is initialized.

taxiway observe up only starts Langfuse. It does not create lab gateway keys and does not start LiteLLM sidecars.

Taxiway writes its own lab lifecycle events (LAB_AGENT_EVENT records) to the lab's local events.jsonl file. They are not sent to Langfuse. Langfuse is reserved for agent/model traffic collected through LiteLLM.

Reset

taxiway observe down          # stop only; keep containers, volumes, and runtime state
taxiway observe rm            # remove containers and clear runtime state
taxiway observe rm --volumes  # also remove observability data volumes
taxiway observe reset         # rm --volumes, then restart

taxiway observe down is non-destructive. It stops Langfuse and preserves the runtime state so taxiway observe up can restart it through the proxy.

taxiway observe rm removes stack containers and clears the observability runtime marker in dev/e2e contexts. With --volumes, Docker also removes observability data volumes.

taxiway observe reset wipes the Postgres volume: all traces are permanently deleted. It preserves the observability .env by default and only regenerates missing values. Use --rotate-secrets if you explicitly want to regenerate observability credentials.

Troubleshooting