What Langfuse records and why it matters
Langfuse is an open-source LLM engineering platform. It records traces of model calls, retrieval steps and agent actions, versions prompts, runs evaluations and manages test datasets. Teams use it to see what an AI feature did for a request, what it cost and how a prompt change affected quality.
Traces usually contain user prompts, retrieved documents and model outputs, so a Langfuse deployment is a store of sensitive data. Self-hosting keeps that content inside infrastructure the organization controls, next to its private model runtimes.
Langfuse announced on January 16, 2026, that it had joined ClickHouse, stating that it stays open source and self-hostable with no planned licensing changes.
Self-hosted architecture
Two application containers and four data services. The v4 migration guide states the architecture is unchanged from v3.
Web container
Serves the UI and public APIs, including ingestion and the OpenTelemetry endpoint. Scales horizontally.
Worker container
Processes ingested events asynchronously and runs evaluations. Its throughput decides how fast traces appear under load.
PostgreSQL
Holds transactional data such as users, projects, prompts and API keys. Langfuse recommends a managed service for production.
ClickHouse
Stores traces, observations and scores. Usually the largest sizing and backup concern. v4 requires version 25.12 or newer.
Redis or Valkey
Cache and job queue between web and worker. v4 requires version 7.0 or newer.
S3-compatible blob storage
Holds raw events, attachments and large exports. Cloud object storage, MinIO or SeaweedFS can fill this role.
Open-source and enterprise features
The repository is MIT-licensed except for its ee directories. Langfuse states all core features and APIs are in OSS without limits. Some additional features need a license key.
| Capability | Langfuse OSS | With an enterprise license key |
|---|---|---|
| Single sign-on | Included, with enterprise providers and SSO enforcement. | Included. |
| Access control | Organization-level roles. | Adds project-level roles and protected prompt labels. |
| Audit and provisioning | Not included. | Audit logs, SCIM and the organization management API. |
| Data governance | Not included. | Data retention policies and server-side data masking. |
| Instance administration | Environment variable configuration. | Instance management API and UI customization. |
Choose a topology and size the data stores
Documented for local use and testing on a single VM, without high availability, scaling or backups. Use it to evaluate features, then move to a production topology before storing sensitive traces.
The Helm chart is the documented production path and can bundle the data stores or use external ones. Teams using the bundled ClickHouse need chart version 2 to reach the ClickHouse version v4 requires.
Use managed PostgreSQL and object storage where policy allows. ClickHouse can run as ClickHouse Cloud or BYOC, which manage backups, or as a self-run cluster, the heaviest operational choice in the stack.
Langfuse can run in a VPC or on-premises with internet access optional. Use MinIO or SeaweedFS for blob storage and point evaluations at an internal model gateway such as LiteLLM.
ClickHouse disk and memory grow with trace volume, payload size, attachments and retention. Worker capacity grows with ingestion rate and evaluations. Measure a representative week of traces from one application during a pilot before committing storage.
Control what reaches Langfuse and who can see it
Applications send data through the Langfuse SDKs or any OpenTelemetry exporter. Langfuse accepts OTLP over HTTP at /api/public/otel, authenticated with a project's public and secret keys. Issue keys per project and environment, and route exporters through an internal collector if you need one place to filter attributes.
Decide before go-live which fields may be traced, and mask personal data and credentials in the application or collector before export. Server-side masking and enforced retention are enterprise features, so an OSS deployment needs a tested procedure for deleting trace data.
Langfuse uses Auth.js and documents SSO providers including Keycloak, Okta, Entra ID and generic OIDC. Once SSO works, disable username and password sign-in, block self-registration or enforce SSO by domain, and enable account linking only where providers verify email addresses.
Store the application secrets from Langfuse's configuration reference in a secret manager and include them in backups. Use TLS on the web endpoint and data store connections, and limit network access to the data stores.
Back up each data store
State is spread across several services. A restore is complete only when all of them return to a consistent point.
| Data store | Approach | Check |
|---|---|---|
| ClickHouse | Managed backups on ClickHouse Cloud or BYOC. Self-run: volume snapshots including coordination volumes, or native BACKUP to S3. | Restore in isolation and confirm recent traces and scores load. |
| PostgreSQL | Managed service backups, or scheduled pg_dump plus volume snapshots. | Projects, prompts and API keys return, and SSO sign-in works. |
| Blob storage | Provider versioning or replication. For MinIO or SeaweedFS, mirror the bucket or snapshot the volume. | Attachments referenced by restored traces open. |
| Secrets and configuration | Helm values or environment files in version control, secrets in a secret manager. | A rebuilt deployment connects to restored data. |
Upgrade from v3 to v4 deliberately
Langfuse v4 became generally available for self-hosted deployments on August 17, 2026, moving traces to an append-only observations model. v3 receives security patches until the end of January 2027, and there is no forced cutover date for self-hosted users.
The migration guide sets minimums of ClickHouse 25.12, PostgreSQL 15 and Redis 7.0. Upgrade ClickHouse first while still on v3, grant the extra privileges v4 needs, let the latest v3 release finish its background migrations, then back up PostgreSQL and ClickHouse immediately before upgrading. There is no automatic downgrade once v4 schema migrations run.
The default write mode rejects data from incompatible SDKs, while dual mode accepts both at higher load and storage cost. Plan SDK upgrades with application teams, and allow roughly three times the disk headroom for a historic backfill. Migrations run on startup, so pin exact image versions to keep each change under your release process.
Langfuse operating ownership
Platform, AI engineering and security teams each own part of Langfuse, and the trace data needs a named owner of its own.
Platform team
- Run the containers and four data stores.
- Monitor ingestion lag, queue depth and ClickHouse disk.
- Run backups and restore tests.
AI engineering
- Instrument applications and keep SDKs current.
- Own prompts, datasets and evaluations.
- Keep trace content to the agreed field list.
Security and privacy
- Approve traced fields and masking rules.
- Review SSO roles, API keys and project access.
- Confirm the deletion procedure runs.
Change record
- Record pinned versions of every component.
- Log upgrade steps, write modes and backfill status.
- Note license key status.
Langfuse deployment questions
Is SSO free in self-hosted Langfuse?
Yes. Langfuse's self-hosted pricing lists enterprise SSO and SSO enforcement in the open-source version. Project-level roles, audit logs and SCIM need a license key.
Can we use OpenTelemetry instead of the SDKs?
Yes, over OTLP HTTP. gRPC ingestion is not supported, so a collector receiving gRPC should export to Langfuse over HTTP.
When should we move to v4?
Before v3 security patches end in January 2027, and before teams need the newest SDK major versions, which require a v4 server. The ClickHouse upgrade can start on v3.
Scope and handover
DeployOpen deploys Langfuse and its data stores inside your cloud account, data center or isolated network, integrates SSO, sets network and secret controls, connects internal model gateways and sets up backups for each store. We plan and rehearse upgrades, including v3 to v4, document the platform and can provide ongoing support. Instrumenting applications is scoped with the teams that own them.
Handover includes topology and sizing assumptions, Helm values in version control, the SSO and role mapping, the approved trace field list with masking rules, restore results for each store, pinned versions and named owners for each operating area.
