Sizing & Scaling

Resource requirements, size profiles, and scaling recommendations for LangWatch

​

Minimum Requirements

​

Docker Compose (local development)

• 4 CPU cores, 16 GB RAM, 50 GB disk
• Suitable for evaluation and small teams (< 5 users)

​

Kubernetes (production)

• Minimum 3 nodes with 4 CPU, 16 GB each
• StorageClass that supports dynamic provisioning
• See size profiles below for detailed per-component requirements

​

Component Resource Defaults

These are the default resource requests and limits from the Helm chart (values.yaml):

Component	CPU Request	CPU Limit	Memory Request	Memory Limit	Storage
LangWatch App	250m	1000m	2Gi	4Gi	10Gi stored objects, shared with the workers
LangWatch Workers	250m	1000m	2Gi	4Gi	---
LangWatch NLP	250m	1000m	256Mi	1Gi	---
LangEvals	1000m	2000m	6Gi	8Gi	---
AI Gateway (2 to 10 replicas, autoscaled)	200m	1000m	256Mi	512Mi	---
Langy	500m	2000m	1Gi	4Gi	---
PostgreSQL	250m	1000m	512Mi	1Gi	20Gi
ClickHouse	2 cores	2 cores	4Gi	4Gi	50Gi
Redis	250m	500m	256Mi	512Mi	10Gi
Prometheus	200m	500m	512Mi	2Gi	6Gi

ClickHouse auto-tunes internal parameters (memory limits, thread pools, merge settings) based on the CPU and memory you allocate. You only need to set clickhouse.cpu and clickhouse.memory.

​

Size Profiles

The Helm chart ships with composable overlay files in examples/overlays/. Use them with helm install -f:

Every figure below is requests/limits as the chart renders it, and the totals are the sum of requests across all replicas. They include the AI Gateway and Langy, which run by default and are a real part of what your cluster has to fit.

​

Development (size-dev.yaml)

For development, demos and small teams.

• LangWatch App: 1 replica, 250m/1 CPU, 1Gi/3Gi memory
• LangWatch Workers: 1 replica, 250m/1 CPU, 768Mi/2Gi memory
• LangWatch NLP: 1 replica, 100m/500m CPU, 512Mi/1Gi memory
• LangEvals: 1 replica, 100m/500m CPU, 768Mi/4Gi memory
• AI Gateway: 2 replicas (autoscaled up to 10), 200m/1 CPU, 256Mi/512Mi memory
• Langy: 1 replica, 500m/2 CPU, 1Gi/4Gi memory
• ClickHouse: 1 CPU, 2Gi memory, 5Gi storage
• PostgreSQL: 100m/500m CPU, 256Mi/512Mi memory, 2Gi storage
• Redis: 50m/250m CPU, 64Mi/256Mi memory, 1Gi storage
• Prometheus: 50m/250m CPU, 128Mi/512Mi memory, 7d retention, 2Gi storage
• Total: ~2.8 CPU, ~6.9 Gi RAM requests

helm install langwatch langwatch/langwatch \
-f examples/overlays/size-dev.yaml \
--set autogen.enabled=true

examples/values-local.yaml is the same sizing without Prometheus (~2.75 CPU, ~6.8 Gi), bundled with NodePort access and images pinned to a locally built local tag. That last part makes it Kind-only: see Local Kubernetes.

​

Minimal (size-minimal.yaml)

The smallest configuration the platform still boots in. Trims the app, NLP, PostgreSQL and Redis further, drops ClickHouse to 1Gi and turns off Prometheus.

• Total: ~2.6 CPU, ~5.2 Gi RAM requests

LangEvals is the one thing this overlay does not shrink much. A single worker holding every local model needs roughly 2.6 Gi resident, so its limit stays at 4Gi. The limit is a ceiling rather than a reservation, so the node only spends that memory once an evaluator loads a model.

​

Production (size-prod.yaml)

For production with single-node ClickHouse.

• LangWatch App: 2 replicas, 500m/2 CPU, 2Gi/4Gi memory, PDB minAvailable 1
• LangWatch Workers: 2 replicas, 500m/2 CPU, 2Gi/4Gi memory
• LangWatch NLP: 1 replica, 250m/1 CPU, 256Mi/1Gi memory
• LangEvals: 1 replica, 1/2 CPU, 4Gi/8Gi memory
• AI Gateway: 2 replicas (autoscaled up to 10), 200m/1 CPU, 256Mi/512Mi memory
• Langy: 1 replica, 500m/2 CPU, 1Gi/4Gi memory
• ClickHouse: 4 CPU, 8Gi memory, 100Gi storage
• PostgreSQL: 250m/1 CPU, 512Mi/1Gi memory, 20Gi storage
• Redis: 500m/1 CPU, 1Gi/3Gi memory, 5Gi storage
• Prometheus: 200m/500m CPU, 512Mi/2Gi memory, 30d retention, 20Gi storage
• Total: ~9.1 CPU, ~23.8 Gi RAM requests

helm install langwatch langwatch/langwatch \
-f examples/overlays/size-prod.yaml \
-f examples/overlays/access-ingress.yaml

​

High Availability (size-ha.yaml)

For production with replicated ClickHouse.

• LangWatch App: 3 replicas, 1/2 CPU, 4Gi/4Gi memory, PDB minAvailable 2
• LangWatch Workers: 3 replicas, 1/2 CPU, 4Gi/4Gi memory, PDB minAvailable 2
• LangWatch NLP: 2 replicas, 250m/1 CPU, 256Mi/1Gi memory
• LangEvals: 2 replicas, 1/2 CPU, 4Gi/8Gi memory
• AI Gateway: 2 replicas (autoscaled up to 10), 200m/1 CPU, 256Mi/512Mi memory
• Langy: 1 replica, 500m/2 CPU, 1Gi/4Gi memory
• ClickHouse: 3 nodes, 4 CPU, 16Gi memory, 300Gi storage each
• ClickHouse Keeper: 3 nodes, 250m/1 CPU, 512Mi/1Gi memory
• PostgreSQL: 250m/1 CPU, 512Mi/1Gi memory, 50Gi storage
• Redis: 500m/1 CPU, 1Gi/3Gi memory, 10Gi storage
• Prometheus: 200m/500m CPU, 512Mi/2Gi memory, 60d retention, 50Gi storage
• Total: ~23.1 CPU, ~85.6 Gi RAM requests

helm install langwatch langwatch/langwatch \
  -f examples/overlays/size-ha.yaml \
  -f examples/overlays/access-ingress.yaml \
  -f examples/overlays/cold-storage-s3.yaml \
  --set clickhouse.objectStorage.bucket=my-langwatch-data \
  --set clickhouse.objectStorage.region=us-east-1

Both production overlays turn off the local-filesystem volume for stored objects, because more than one replica cannot share it. Set app.dataplane.enabled: true with an S3 or Azure Blob bucket, or stored objects (audio, images and documents) land on the pods’ ephemeral disk and are lost on restart. Both commands also need the Secrets from Provide the Secrets, or --set autogen.enabled=true for a test install.

​

Throughput by size

How much trace data each profile can take. Each profile accepts spans faster than it processes them: a burst above the processing rate waits in a queue and is worked through once traffic drops.

Profile	Accepts (spans per second)	Processes (spans per second)	Spans per day	Spans per month	ClickHouse disk per day	Redis memory limit
size-minimal.yaml	~250	~50	~4M	~130M	~4 GB	128Mi
size-dev.yaml	~600	~200	~17M	~520M	~17 GB	512Mi
size-prod.yaml	~2,500	~700	~60M	~1.8B	~60 GB	3Gi
size-ha.yaml	~2,500	~800	~70M	~2.1B	~70 GB	3Gi

• These rates are for traffic from many projects. One project on its own processes about 60 spans per second under the default per-project limit: if most of your traffic comes from one project, raise the limit.
• Per day, per month and disk follow the processing rate, which is what the install keeps up with all day.
• Treat these as ceilings and plan to run at about 70% of them. Long prompts and completions lower them.
• Per day and per month assume the same rate around the clock. Size for your busiest hour.
• Disk is an estimate at about 1 KB per span. size-prod.yaml gives ClickHouse 100Gi, which fills in under two days at full rate: give it more storage or turn on cold storage.
• size-dev.yaml ships Redis at 256Mi. Raise redis.master.resources.limits.memory to 512Mi to reach its rate.
• size-minimal.yaml is held back by ClickHouse memory. Setting clickhouse.memory to 2Gi roughly doubles its processing rate.

​

Changing size-prod.yaml

What size-prod.yaml processes with one setting changed:

Change	Processes (spans per second)
None	~700
workers.replicaCount: 4	~800: Redis CPU is then the limit
clickhouse.cpu: 2, clickhouse.memory: 4Gi	~200
Valkey instead of Redis	~700, with about 10% less CPU on the queue
All traffic from one project	~60 for that project, under the default per-project limit

Each worker replica processes about 350 spans per second on about one core, however high its CPU limit, so to process more, add replicas rather than CPU. More replicas raise the rate until Redis reaches 1 CPU, at about 800 spans per second. Every 100 spans per second needs about:

Component	CPU
LangWatch Workers	0.3 core
LangWatch App	0.15 core
ClickHouse	0.16 core
Redis	0.12 core, up to 1 core in total
PostgreSQL	0.03 core

Redis needs about 2.5 MiB of memory limit for each span per second; the table rounds up to leave room for bursts. It uses up to half of its limit and keeps the rest free for snapshots.

The queue for bursts lives in Redis too. Each waiting span takes about 8 KB, so a minute at 500 spans per second above the processing rate needs about 240 MiB more.

To accept more, add app replicas (each core takes about 700 spans per second) and give Redis up to 1 CPU.

​

Per-project limit

Each project gets a fair share of the workers, so one busy project can’t slow down the others.

To give a single project more, raise LANGWATCH_DISPATCH_TENANT_CAP in workers.extraEnvs: the number of traces one project can have in progress at once (default 50). At the default, one project on its own processes about 60 spans per second. Setting it to 0 turns the limit off and lets one project take every worker.

​

Scaling Guidelines

​

What to scale first

Bottleneck	Component to Scale	How
Redis refuses writes (OOM command not allowed) or restarts with OOMKilled	Redis	Raise redis.master.resources.limits.memory (about 2.5 MiB per span/s, see Throughput by Size)
Redis CPU near its limit	Redis	Raise redis.master.resources.limits.cpu, up to 1
Trace ingestion is slow, each worker near one core	LangWatch Workers	Increase workers.replicaCount (about 350 spans per second each)
One project falls behind while others keep up	LangWatch Workers	Raise LANGWATCH_DISPATCH_TENANT_CAP in workers.extraEnvs (default 50)
UI is slow, many concurrent users	LangWatch App	Increase app.replicaCount
ClickHouse queries are slow, trace summaries lag	ClickHouse	Increase clickhouse.cpu and clickhouse.memory
Evaluations are slow	LangEvals	Increase langevals.replicaCount
Topic clustering is slow	LangEvals	Increase langevals.replicaCount

​

Horizontal Pod Autoscaler (HPA)

# Example HPA for workers
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: langwatch-workers
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: langwatch-workers
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70

​

Storage Sizing

​

ClickHouse hot storage

• ~1 KB per span (compressed, varies with payload size)
• 100K traces/day with avg 5 spans = ~500 MB/day = ~15 GB/month
• 1M traces/day with avg 5 spans = ~5 GB/day = ~150 GB/month
• Plan for 3-6 months of hot data before cold storage kicks in

​

ClickHouse cold storage (S3)

• Enable with clickhouse.cold.enabled: true
• Default TTL: 49 days (data older than this moves to S3). We recommend multiples of 7 to align with ClickHouse’s weekly partition boundaries
• S3 cost is typically 10-20x cheaper than SSD storage

​

PostgreSQL

• Grows slowly: metadata only (users, projects, configurations)
• 10-20 GB is sufficient for the size profiles on this page

​

Redis

• Minimal storage: job queue, cache and sessions
• 1-5 GB is sufficient

​

Redis or Valkey

The chart runs Redis by default. To run Valkey instead, add -f examples/overlays/redis-valkey.yaml. Both take the same load. Valkey uses about 10% less CPU, which helps only when Redis CPU is the limit.

Choose Valkey when you first install. Valkey can’t read the data Redis has saved, so switching an existing install means starting Redis empty: let the workers finish their queued jobs first, and expect everyone to sign in again.

For an external server, use Redis 7.0 or later, or Valkey 7.2 or later.

​

Cloud Instance Recommendations

Cloud	General Nodes	ClickHouse Nodes	Notes
AWS	m7g.xlarge (4 vCPU, 16 GB)	r7g.2xlarge (8 vCPU, 64 GB)	Graviton (ARM) for cost efficiency
GCP	e2-standard-4 (4 vCPU, 16 GB)	n2-highmem-8 (8 vCPU, 64 GB)
Azure	Standard_D4s_v5 (4 vCPU, 16 GB)	Standard_E8s_v5 (8 vCPU, 64 GB)

For ClickHouse, prioritize memory over CPU. ClickHouse benefits from large memory for caching and merge operations.