Langfuse launches AI Gateway Learn more

ClickHouse for self-hosted Langfuse: sizing and operations

ClickHouse stores the traces, observations, and scores in Langfuse, and it is the component self-hosters spend the most operations time on. Most of that time goes to a short list of problems that show up in a predictable order: picking a deployment, getting the version right, then disk growth. This guide covers each one and links to the configuration reference.

TL;DR: Use ClickHouse Cloud or BYOC for larger deployments, or the official ClickHouse Kubernetes Operator if you run ClickHouse yourself. Langfuse v4 needs ClickHouse 25.12 or later, and you should run a release that still gets security patches. Start with at least 2 CPUs and 8 GiB of memory. Most disk problems come from missing retention and from ClickHouse system log tables, which have no TTL by default and which Langfuse never reads.

Deployment architecture
UI, API, and SDK clients connect to Langfuse Web. Web connects to PostgreSQL, Redis or Valkey, ClickHouse, and S3 or blob storage. Redis queues jobs for Langfuse Worker, which connects to PostgreSQL, ClickHouse, and S3. Both containers can optionally connect to LLM providers: Web for the playground, Worker for evaluations. The optional Langfuse AI gateway receives model requests from applications and coding agents, resolves gateway keys and uploads traces through Langfuse Web, and relays the requests to the LLM providers. The application containers, gateway, and storage run in your VPC or on-premises. The LLM providers can also run in the same VPC or a peered VPC.VPC / on-premisesUI, API & SDKsApps & agentsModel requestsResolve + tracesRequestsPlaygroundEvaluationsRelayAI GatewayOptional (beta)langfuse/ai-gatewayLangfuse WebUI & API serverlangfuse/langfuseLangfuse WorkerAsync event processinglangfuse/workerPostgreSQLTransactional dataRedis / ValkeyCache & job queueClickHouseObservability dataS3 / Blob storageEvents & attachmentsLLM providersOptional (bring your own)
Web connectionsWorker connectionsOptional

The optional AI gateway relays model requests from your apps and coding agents to your LLM providers and records them in Langfuse. LLM providers can also run in the same VPC or a peered VPC.

Choose a deployment

OptionSupport levelGood for
ClickHouse CloudOfficialMost production deployments; managed scaling and backups
ClickHouse BYOCOfficialManaged ClickHouse with the data plane in your own cloud account
ClickHouse Kubernetes OperatorOfficialRunning ClickHouse yourself on Kubernetes, with upgrades and high availability
Bundled in the Langfuse Helm chartCommunityGetting started on Kubernetes; uses the operator from chart v2.0.0
Single Docker containerCommunityLocal development only

ClickHouse Cloud and BYOC separate storage from compute, so storage can grow without resizing compute, and they support separate compute groups for reads and writes. Self-managed ClickHouse means you own disk expansion, replicas, and merge behavior. See ClickHouse deployment options.

Get the version right

Each Langfuse major release sets a minimum ClickHouse version: 25.12 for v4 and 24.3 for v3, as of November 2026. Minor and patch releases of Langfuse never raise it.

The minimum version is a compatibility guarantee, not a security recommendation. ClickHouse patches only its recent releases, so pick a version the ClickHouse security policy lists as supported, such as the latest LTS. See supported versions.

Size it

Start at the minimum of 2 CPUs and 8 GiB of memory, and grow from measurements. Trace volume depends on how many observations each trace contains and how large inputs and outputs are, not on request count. A single ClickHouse shard can hold multiple terabytes of tracing data before horizontal scaling becomes a question.

Signs you need more:

  • Slow dashboards or API reads during ingestion peaks. On ClickHouse Cloud or BYOC, route reads to a separate compute group with CLICKHOUSE_READ_ONLY_URL.
  • Ingestion backlog in the worker. Scale the worker containers first, see ingestion throughput.
  • Steady disk growth. See the next section.

Keep disk usage under control

Three settings cover most disk problems:

  1. Data retention. A data retention policy per project deletes old traces in ClickHouse and blob storage consistently. It needs an Enterprise license on self-hosted deployments. Without it, ClickHouse TTL on the tracing tables is the alternative.
  2. System log tables. Tables such as trace_log, text_log, and metric_log have no TTL by default and can use more disk than your traces. Langfuse doesn't read them, so disable or cap them. See ClickHouse system log tables.
  3. Lightweight deletes. On ClickHouse 25.7 and later, lightweight deletes and updates reduce background merge work on deletion-heavy workloads. See slow or timing-out deletions.

Back it up

ClickHouse Cloud and BYOC back up automatically. For self-managed ClickHouse, use volume snapshots or a backup tool on Kubernetes, and test restores. See backup strategies. Langfuse also writes incoming events to blob storage first, which helps if ClickHouse is briefly unavailable.

Other things to configure

  • Timezone: ClickHouse must run in UTC. See timezones.
  • User permissions: the Langfuse user needs specific grants, including on system tables. See user permissions.
  • Encryption at rest: use encrypted disks or blob storage as a disk. See ClickHouse encryption.
  • Direct access: you can query Langfuse tables for custom tools, but don't change the schema. See direct ClickHouse access.

For how Langfuse Cloud runs ClickHouse at scale, see How Langfuse runs ClickHouse at agent scale.

FAQ

Why does Langfuse need ClickHouse?

Traces are large, append-heavy, and queried with aggregations across millions of rows. ClickHouse stores them in columns and aggregates them quickly, which Postgres alone can't do at that volume. Postgres still stores transactional data such as users, projects, and prompts.

Can I use another managed ClickHouse service?

Yes, as a community-supported option. It needs to meet the minimum version, support the required settings and grants, and run in UTC.

ClickHouse disk is filling up. What should I check first?

Run the query on the scaling page to list the largest tables. If system log tables are near the top, disable or cap them. If tracing tables are, set a retention policy or a TTL.


Was this page helpful?