Langfuse: self-hosted LLM tracing, evals and prompt management

What Langfuse solves for teams shipping LLM features

The README frames Langfuse as a platform to develop, monitor, evaluate and debug AI applications, and the feature list maps to four distinct jobs. Observability covers LLM calls plus the surrounding logic: retrieval, embedding and agent actions. Prompt management covers central storage and versioning of prompts. Evaluations cover LLM-as-a-judge, code evaluators, user feedback and manual labeling. Datasets cover test sets and benchmarks. The intended user is a team building an application on top of a model API, not a team training models. If your work is fine-tuning or serving weights, the tracing and prompt features have little to attach to. The repository layout backs this up: web/ and worker/ are the two runtime services, packages/ holds shared code, and ee/ sits alongside them. The README also states that since January 2026 Langfuse is part of ClickHouse, which explains why the platform is built on the ClickHouse database.

How traces, prompts and evaluations move through the system

The architecture visible in docker-compose.yml is a four-dependency stack. langfuse-worker depends on postgres, minio, redis and clickhouse, each with a health condition, so the worker will not start until all four report healthy. Postgres holds transactional data, ClickHouse holds the analytical workload behind traces and metrics, Redis handles caching, and Minio provides S3-compatible object storage. The web service is the only component the compose file exposes broadly, on port 3000; the worker binds to 127.0.0.1:3030 and the comment in the file recommends restricting inbound traffic to langfuse-web and minio only. Data flows in through the SDKs or the API, is written by the worker, and is queried back through the web UI and API. Prompt management depends on caching on both the server and client side, which the README says is what keeps prompt iteration from adding latency to the application. That is the design trade-off: you get central prompt control, but the client SDK has to participate in the cache for the latency claim to hold.

Installing Langfuse locally with Docker Compose

The README gives a local path that it describes as running Langfuse on your own machine in five minutes. Clone the repository and bring up the compose file:

git clone --depth=1 https://github.com/langfuse/langfuse.git
cd langfuse

docker compose up

After the four dependencies pass their health checks, the web service is reachable on port 3000. Before you run this anywhere other than a laptop, edit the credential placeholders. The compose file marks them with CHANGEME: DATABASE_URL, SALT and ENCRYPTION_KEY. The ENCRYPTION_KEY comment gives the exact generation command:

openssl rand -hex 32

For a production deployment the README points elsewhere: a single VM with Docker Compose, Kubernetes with Helm, which it calls the preferred production deployment, and Terraform templates for AWS, Azure and GCP. One operational detail is worth reading before you leave the default stack running. The compose file inherits the Docker daemon logging configuration, and the default json-file driver does not rotate logs unless you set max-size and max-file. The README warns that this can exhaust disk space, that you should not rotate or truncate Docker-managed JSON files with external tools, and that after changing daemon defaults you must restart Docker and recreate containers, not just restart them.

Sending a first trace from the Python SDK

The README lists typed SDKs for Python and JS/TS and an OpenAPI spec, and the repository publishes the Python package as langfuse on PyPI. The self-hosted stack exposes the same ingestion endpoint as Langfuse Cloud, so the SDK configuration is a matter of pointing the client at your own host and keys. The README does not include a full SDK example, so the concrete call sequence belongs to the tracing documentation rather than to this page. What the repository does confirm is that instrumentation is the entry point: you instrument the application, traces land in Langfuse, and from there you inspect logs and user sessions. For prompt management, the README describes the workflow as managing prompts centrally and iterating on them without redeploying, with the caching layer doing the work. The practical order is to get a trace visible in the UI first, then move a hardcoded prompt into prompt management, then attach an evaluation to a dataset run.

The operational weight of self-hosting Langfuse

The honest limitation is in the dependency list. A self-hosted Langfuse is not one container; it is ClickHouse, Postgres, Redis and Minio plus the web and worker services. ClickHouse is an analytical database with its own upgrade and disk behaviour, and the README's own logging warning shows the class of problem you inherit: container log growth that is invisible until a disk fills. The README notes that its logging guidance covers container stdout and stderr, not database data volumes or ClickHouse's internal log files, so there is a second retention surface the compose defaults do not address. This is the wrong tool if you want a single binary, or if you have no appetite for operating a columnar database next to your transactional one. It is also the wrong tool if your only need is a prompt registry with an API, because you would be running a tracing and evaluation platform to get a key-value store with versions.

Langfuse compared with LangSmith

The comparison people search for is Langfuse vs LangSmith, and the difference is deployment model rather than feature checklist. Langfuse offers both a managed cloud and a self-hosted path, and the README documents the self-hosted path in detail: local Docker Compose, VM, Kubernetes with Helm, Terraform for three clouds. LangSmith is a hosted service from LangChain. If your constraint is that trace data cannot leave your infrastructure, that constraint alone decides the question in Langfuse's favour, and the cost is the four-dependency stack described above. If your constraint is that nobody on the team wants to run ClickHouse, the hosted option is the shorter path. The README also lists integrations with OpenTelemetry, LangChain, the OpenAI SDK and LiteLLM, so Langfuse is designed to sit alongside a framework rather than replace it.

Licence, releases and upgrade cost

The licence signal is split and you should resolve it before adopting. package.json declares "license": "MIT" for the workspace, while the repository licence field is NOASSERTION, and an ee/ directory exists at the top level. The README links to a LICENSE file but the cleaned text does not state its terms. This is not legal advice: read LICENSE and the ee/ directory yourself and decide whether the enterprise layer touches features you need. On releases, the version in package.json is 4.46.0, matching the most recent tag, and the last push was on 2026-09-25. The project also publishes a self-hosting update list, which the README describes as email about important features and new releases for open source Langfuse, self-hosting updates only. Upgrading means migrating Postgres and ClickHouse schemas; the root package.json exposes db:migrate and ch:migrations:materialize scripts, which tells you schema changes are a first-class part of the release process rather than something that happens silently.

Editorial conclusion

Adopt Langfuse if you need traces, prompt versions and evaluation runs in one place and you are willing to operate Postgres, Redis, ClickHouse and object storage to self-host it, or to send data to Langfuse Cloud instead. Do not adopt it if you only need a hosted prompt registry, or if a single-node deployment without ClickHouse is a hard constraint. Before committing, verify the licence situation: package.json declares MIT while the repository licence field is NOASSERTION, and the ee/ directory suggests an enterprise layer. Then confirm your deployment path against the self-hosting documentation, because the README points to separate pages for local, VM and Kubernetes installs.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes