Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

2.4 KB
Raw Blame
---
sidebar_position: 0
slug: /tracing
sidebar_custom_props: {
  categoryIcon: LucideLocateFixed
}
---
# Tracing

Observability & Tracing with Langfuse.

---

:::info KUDOS
This document is contributed by our community contributor [jannikmaierhoefer](https://github.com/jannikmaierhoefer). 👏
:::

RAGFlow includes a [Langfuse](https://langfuse.com) integration for recording chat traces and chat-model generation observations.

:::info NOTE
- A Langfuse workspace, either cloud-hosted or self-hosted, with a _Project Public Key_ and _Secret Key_.
:::

---

## 1. Collect Your Langfuse Credentials

1. Sign in to your Langfuse dashboard.
2. Open **Settings ▸ Projects** and either create a new project or select an existing one.
3. Copy the **Public Key** and **Secret Key**.
4. Note the Langfuse **host** (e.g. `https://cloud.langfuse.com`). Use the base URL of your own installation if you self-host.

> The keys are _project-scoped_: one pair of keys is enough for all environments that should write into the same project.

---

## 2. Add the Keys to RAGFlow

RAGFlow stores the credentials _per tenant_. You can configure them either via the web UI or the HTTP API.

1. Log in to RAGFlow and click your avatar in the top-right corner.
2. Select **API ▸ Scroll down to the bottom ▸ Langfuse Configuration**.
3. Fill in your Langfuse **Host**, **Public Key**, and **Secret Key**.
4. Click **Save**.


Once saved, the Go chat pipeline uses these credentials for chat requests that use a Dataset or web search.

---

## 3. Run a Pipeline and Watch the Traces

1. Send a message through a Chat configured with a Dataset or web search.
2. Open your Langfuse project ▸ **Traces**.
3. Find the trace named `openai_chat` for the request.

The trace contains:

- One `openai_chat` trace containing the tenant ID as `userId`, the chat ID as `sessionId`, and metadata indicating whether streaming was enabled and how many Datasets were configured.
- One `chat` generation observation containing the model name and the prompt, citation prompt, and model message list as input.
- A completion update for that generation containing the recorded output summary and prompt, completion, and total token counts.

Langfuse delivery runs asynchronously, so a tracing delivery failure does not stop the chat response.

:::tip NOTE
Use the recorded generation input, output, model name, and token usage to inspect a traced chat request.
:::