> ## Documentation Index
> Fetch the complete documentation index at: https://learn.kubit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Kubit with Langfuse

> Add Kubit next to Langfuse with the agent plugin, or read self-hosted Langfuse traces in place from your ClickHouse.

Kubit works with Langfuse in two ways. If your app sends spans to Langfuse, the agent plugin adds `KubitSpanProcessor` next to the Langfuse processor and Langfuse keeps receiving every span. If you self-host Langfuse, Kubit can read its traces in place from your ClickHouse. This page helps you pick one and points to the steps.

## Pick a Path

| **Your setup** | **Path** | **What changes in your app** |
| - | - | - |
| Your app sends spans to Langfuse, Cloud or self-hosted | **Agent** workspace with the agent plugin | `KubitSpanProcessor` is added next to the Langfuse processor |
| Self-hosted Langfuse storing traces in your ClickHouse | **Langfuse** workspace reading ClickHouse | Nothing |
| You want a quick test first | **Sandbox** workspace with a Langfuse export | Nothing |

## Next to Langfuse in Your App

The `/kubit-integrate` skill in the agent plugin detects Langfuse as the place your traces go today. It adds `KubitSpanProcessor` next to Langfuse's processor, so Langfuse keeps receiving every span and Kubit gets a copy. Run it in Claude Code or Cursor. [Agent plugin](https://learn.kubit.ai/agent-observability/integrate/agent-plugin.md) has the steps.

| **Constraint** | **Value** |
| - | - |
| **Langfuse with LangChain** | Needs `langfuse >= 3` (`from langfuse.langchain import CallbackHandler`) or `@langfuse/langchain`. Below v3, `langfuse.callback` and `langfuse-langchain` send spans outside OpenTelemetry and **aren't supported**. |
| **More than one sink** | The skill asks you to pick one |

The extraction mapping template `default-agent` reads Langfuse keys such as `langfuse.user.id`, `langfuse.session.id`, `langfuse.release` and `langfuse.environment`. A workspace created by `/kubit-integrate` starts on `default-otel`, which reads only the OpenTelemetry GenAI keys. [Check the extraction mapping](https://learn.kubit.ai/agent-observability/get-started/quickstart.md#check-the-extraction-mapping) shows how to switch.

## Self-Hosted Langfuse on ClickHouse

A self-hosted Langfuse stores its traces in your ClickHouse, so Kubit can query them there.

1. Connect your ClickHouse. See [Connect ClickHouse](https://learn.kubit.ai/warehouses/connect/clickhouse.md).
2. Create a workspace with the **Langfuse** origin (`Langfuse traces in ClickHouse`) and pick the ClickHouse connection.

   ![Create Workspace dialog with Workspace Name Support Agent, Workspace Timezone Europe/Athens (UTC+2\*) and Origin Langfuse, with the hint Langfuse traces in ClickHouse, above the Continue button.](https://mintcdn.com/kubit/iy-nIyF9Xtsr91WV/images/agent-observability/integrate/create-workspace-langfuse.png?fit=max\&auto=format\&n=iy-nIyF9Xtsr91WV\&q=85\&s=9a6c80673414bda9727a144b02d8ae53)
3. The workspace opens on the **Langfuse** preset tab in the [Modeler](https://learn.kubit.ai/warehouses/modeler.md#agent-observability-presets). Fill in the fields below, review **Tables to create**, then click **Validate and use Langfuse**.

| **Field** | **Required** | **Value** |
| - | - | - |
| **Events table** | Required | The Langfuse v4 events table as `database.table`, by default `default.events_full`. Type it or click **Browse warehouse**. |
| **Project ID** | Optional | From the Langfuse project settings. Leave it blank to read every project in the table. |
| **Run completeness** | Required | **Wait for ingestion to settle**, or **Source contains completed runs** |

Under **Tables to create**, check **Price table** and **Evaluator result tables**. The Evaluator result tables let the Evaluator run and save its labels. **Created in** shows where they go, and you can pick another location.

> [!WARNING]
>
> The **Schema** tab stays grayed out until you apply the preset, with the tooltip `Apply the Langfuse preset first. Mapping a table by hand would turn it off for good.` Once a table is mapped by hand, the preset is off for that workspace and can't be turned back on.

Langfuse Cloud keeps traces in Langfuse's own storage, which Kubit can't read in place. Use the agent plugin path instead.

| **Constraint** | **Value** |
| - | - |
| **Langfuse version** | v4 only. The preset reads the single `events_full` table. The v2 and v3 table layouts **aren't supported**. |
| **Warehouse** | ClickHouse only. Otherwise the preset fails with `Langfuse sources require a ClickHouse connection.` |
| **Required columns** | `project_id`, `trace_id`, `span_id`, `parent_span_id`, `name`, `type`, `level`, `status_message`, `trace_name`, `environment`, `session_id`, `user_id`, `provided_model_name`, `input`, `output` (String), `start_time`, `end_time`, `event_ts` (DateTime64), `usage_details`, `cost_details` (Map). A missing or mistyped column fails with `Langfuse requires <column> with type <type>.` |
| **Langfuse scores** | Not read by the preset |

## Quick Test With a Langfuse Export

To try Kubit on traces you already have, export Langfuse observations to a JSONL file and upload it to a **Sandbox** workspace. Kubit reads no scores from the observations, so add them as a separate labels file. [Upload traces to a Sandbox workspace](https://learn.kubit.ai/agent-observability/integrate/sandbox-upload.md#langfuse) has the export commands and the upload steps.

## Next Steps

* [Agent plugin](https://learn.kubit.ai/agent-observability/integrate/agent-plugin.md): the steps for adding Kubit next to Langfuse.
* [Modeler](https://learn.kubit.ai/warehouses/modeler.md): presets and table mapping for warehouse workspaces.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.