Skip to main content

Tracing

Observability & Tracing with Langfuse.

KUDOS

This document is contributed by our community contributor jannikmaierhoefer. 👏

RAGFlow includes a Langfuse integration for recording chat traces and chat-model generation observations.

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 knowledge base or web search.

3. Run a Pipeline and Watch the Traces

  1. Send a message through a Chat configured with a knowledge base 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 knowledge bases 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.

NOTE

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