Langfuse is an open-source platform that records everything your AI agent does (every model call, its cost, its latency and its output) so you can debug and evaluate it with data instead of guesswork. The best part is that you can self-host the whole thing with Docker Compose, so your traces never leave your server. In this guide you will see what Langfuse is, how to deploy it, what data model it uses (traces, spans and generations), how to instrument an agent with OpenTelemetry and how to set up evaluations with datasets. The same explanation is available in Spanish.

Key takeaways

  • Langfuse is an open-source LLM engineering platform (MIT licence, except the ee/ folder of enterprise features); it has over 31,300 stars on GitHub and its stable branch is v3, with a new release almost daily (the latest, v3.218.0, from 16 July 2026).
  • It is self-hostable: a single docker compose up brings up the web UI on port 3000 with four data stores behind it, so your traces stay in your own infrastructure.
  • Its data model is traces, which group observations of type span (a unit of work) and generation (a model call, with its tokens, cost and latency).
  • Instrumenting an agent takes one decorator: the Python SDK v3 is built on OpenTelemetry, the open tracing standard, and ships direct integrations for OpenAI, LangChain, LiteLLM and LlamaIndex.
  • It goes beyond logging: it manages prompts, stores test datasets and runs evaluations (including an LLM judge) to compare versions of your agent with objective metrics.

What is Langfuse?

Langfuse is an observability and evaluation platform for applications that use language models. Its own documentation defines it as "an open source LLM engineering platform": it goes beyond system metrics like CPU or memory and understands the concepts specific to an AI agent, namely the prompts, model responses, tokens consumed, dollar cost and the tools it calls.

The problem it solves is concrete. When an agent built with the Anthropic SDK or a LangGraph graph misbehaves, a print to the console is useless: you cannot see the exact prompt the model received, how many iterations the loop ran or how much each attempt cost you. Langfuse records that full execution tree and shows it to you on a navigable timeline.

The project started at the Y Combinator accelerator (Winter 2023 batch) and has become one of the sector’s references: it holds more than 31,300 stars on GitHub. Its code is free under the MIT licence, with the sole exception of the ee/ folder, which groups enterprise features gated behind a licence key. Everything you need to observe and evaluate agents is in the open part.

Deploying it with Docker Compose

Langfuse’s big advantage over a cloud service is that you can run it entirely on your own machine, so neither your users’ prompts nor their responses ever leave your network. Startup is the classic three commands:

git clone https://github.com/langfuse/langfuse.git
cd langfuse

    # Brings up the web UI on http://localhost:3000
docker compose up -d

Behind that single command, four data stores come up, each with its own job: Postgres holds transactional data (users, projects, prompts); ClickHouse is the analytical database that absorbs the high volume of traces; Redis acts as a cache and event queue; and an S3-compatible store (by default a MinIO container) keeps the raw events and attachments. That separation is what lets Langfuse ingest millions of traces without choking.

The docker compose that ships with the repository is meant for testing and small deployments: it includes neither high availability nor automatic horizontal scaling (that is what the Kubernetes chart is for). Before exposing it in production, change every secret marked # CHANGEME in docker-compose.yml, especially NEXTAUTH_SECRET, SALT, ENCRYPTION_KEY and the database passwords. With the container up, open http://localhost:3000, create the first account and a project, and note the API key pair (pk-lf-… and sk-lf-…) you will use to send traces.

Traces, spans and generations

To get the most out of Langfuse it helps to be clear about its data model, which is deliberately simple. The root piece is the trace: it represents one complete request from start to finish, for example "the user asked X and the agent replied Y". Inside a trace hang the observations, and there are three types:

  • Span: a unit of work with a duration, such as a retrieval step against a vector database or a tool execution. Spans nest to form the execution tree.
  • Generation: a special kind of span for model calls. It captures the model used, the input prompt, the response, the input and output tokens, the computed cost and the latency.
  • Event: a single point in time, with no duration, to mark milestones.

Above traces, sessions group several traces from one conversation, and scores attach a quality value to any trace, numeric, categorical or boolean, which may come from a user, a rule or a judge model. With those four pieces (traces, observations, sessions and scores) you can describe any AI application, from a simple chatbot to a multi-agent system in the style of CrewAI.

Instrumenting an agent with OpenTelemetry

This is where Langfuse shines for its pragmatism. The Python SDK v3 is built on OpenTelemetry, the industry’s open standard for tracing, so it does not lock you into a proprietary format. Installing it is a single command:

pip install langfuse

The fastest way to instrument code is the @observe() decorator: wrap any function and Langfuse automatically creates a span with its input arguments and its return value. For model calls there is an even better shortcut: importing the OpenAI client from langfuse.openai turns every request into a full generation without touching anything else.

from langfuse import observe
from langfuse.openai import openai  # already-instrumented OpenAI client

@observe()
def answer(question: str) -> str:
    # This call logs itself as a generation,
    # with model, tokens, cost and latency included.
    response = openai.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": question}],
    )
    return response.choices[0].message.content

answer("Summarise what agent observability is")

Set the three environment variables LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY and LANGFUSE_HOST (pointing at your http://localhost:3000) and, as soon as you run the function, you will see the trace appear in the UI. Because the SDK builds on OpenTelemetry, any library already instrumented with that standard exports its spans to Langfuse with no extra code, and there are direct integrations for LangChain, LiteLLM and LlamaIndex.

Evaluations and datasets

Observing is the first step; the second is measuring whether your agent gets better or worse when you change a prompt or a model. Langfuse solves this with two tools that work together. A dataset is a collection of test cases, each with an input and, optionally, the expected output; you can build it by hand or promote real traces you care about into it from the UI.

Against that dataset you run an experiment: you run your agent over each case and Langfuse saves each result as a trace linked to the dataset. Then you apply evaluators that assign scores: they can be deterministic checks (does the answer contain the right figure?) or an LLM judge, that is, another model you ask to rate correctness or tone against a rubric. The UI compares two runs side by side, so you can see at a glance whether the new prompt version raises or lowers the average score. It is the same rigour you would apply to serving a model with vLLM in production, but applied to answer quality instead of server throughput.

Frequently asked questions

Is Langfuse really free and open source?

Yes. The bulk of Langfuse, including all of the observability, prompt management, datasets and evaluations, is free software under the MIT licence, and you can self-host it at no cost. The only exception is the repository’s ee/ folder, which groups enterprise features (such as enterprise single sign-on or advanced permissions) gated behind a paid licence key. You do not need it to observe and evaluate agents.

What is the difference between Langfuse and OpenTelemetry?

OpenTelemetry is an open standard and a set of libraries to generate and transport traces, but it includes neither storage nor a UI. Langfuse uses OpenTelemetry as the base of its SDK and adds what is missing: a specialised database (ClickHouse), an interface to explore the traces and the evaluation and prompt-management layers. In short, OpenTelemetry produces the traces and Langfuse receives them, stores them and lets you work with them.

Can I use Langfuse with local models?

Yes. Because the SDK instruments your code, not the provider, it works with any model, including those you run on your own machine with Ollama through its OpenAI-compatible API. By self-hosting Langfuse and serving the model locally you get a complete agent platform in which no data leaves your network, which is key in environments with strict privacy requirements.

Conclusion

Langfuse fills the gap between "my agent works on my laptop" and "my agent works in production and I know why". With a docker compose up you get a complete observability platform that records every trace, span and generation, computes the cost and latency of each call, and lets you evaluate changes with datasets and an LLM judge, all within your own network and under the MIT licence. The next step is to clone the repository, bring up the container, install the SDK with pip install langfuse and add an @observe() to the first function of your agent to watch your first trace appear.

Sources: [1] Official Langfuse documentation[1], [2] Langfuse on GitHub[2], [3] langfuse package on PyPI[3], [4] OpenTelemetry, the tracing standard[4].

Visitas: 0

Sources

  1. Official Langfuse documentation
  2. Langfuse on GitHub
  3. langfuse package on PyPI
  4. OpenTelemetry, the tracing standard

Route: AI Agents in Production: Evaluation and Reliability