Cache (Redis/Valkey)

Langfuse uses Redis/Valkey as a caching layer and queue. It is used to accept new events quickly on the API and defer their processing and insertion. This allows Langfuse to handle request peaks gracefully.

You can use a managed service on AWS, Azure, or GCP, or host it yourself. At least version 7 is required and the instance must have maxmemory-policy=noeviction configured.

This guide covers how to configure Redis within Langfuse and what to keep in mind when bringing your own Redis.

Configuration

Langfuse accepts the following environment variables to fine-tune your Redis usage. They need to be provided for the Langfuse Web and Langfuse Worker containers.

OR

Deployment Options

This section covers different deployment options and provides example environment variables.

Managed Redis/Valkey by Cloud Providers

Amazon ElastiCache, Azure Cache for Redis, and GCP Memorystore are fully managed Redis services. Langfuse handles failovers between read-replicas and supports Redis cluster mode for horizontal scaling.

For standalone Redis instances, use the standard configuration:

REDIS_CONNECTION_STRING=redis://username:password@your-redis-endpoint:6379

For Redis cluster mode, enable cluster support:

REDIS_CLUSTER_ENABLED=true
REDIS_CLUSTER_NODES=your-cluster-endpoint:6379
REDIS_AUTH=your-redis-password  # if authentication is enabled

Ensure that your Langfuse container can reach your Redis instance within the VPC.

Redis on Kubernetes (Helm)

Bitnami offers Helm Charts for Redis and Valkey. We use the Valkey chart as a dependency for Langfuse K8s. See Langfuse on Kubernetes (Helm) for more details on how to deploy Langfuse on Kubernetes.

Example Configuration

For a minimum production setup, we recommend to use the following values.yaml overwrites when deploying the Clickhouse Helm chart:

valkey:
  deploy: true
  architecture: standalone
  primary:
    extraFlags:
      - "--maxmemory-policy noeviction" # Necessary to handle queue jobs correctly
  auth:
    password: changeme

Set the following environment variables to connect to your Redis instance:

REDIS_CONNECTION_STRING=redis://default:changeme@<chart-name>-valkey-master:6379/0

Docker

You can run Redis in a single Docker container. As there is no redundancy, this is not recommended for production workloads.

Example Configuration

Start the container with

docker run --name redis \
  -p 6379:6379 \
  redis --requirepass myredissecret --maxmemory-policy noeviction

Set the following environment variables to connect to your Redis instance:

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_AUTH=myredissecret

Redis Cluster Mode

Redis cluster mode enables horizontal scaling by distributing data across multiple Redis nodes. Langfuse supports Redis cluster mode for high-availability and increased throughput scenarios.

Configuration

To enable Redis cluster mode, set the following environment variables:

REDIS_CLUSTER_ENABLED=true
REDIS_CLUSTER_NODES=redis-node1:6379,redis-node2:6379,redis-node3:6379,redis-node4:6379,redis-node5:6379,redis-node6:6379
REDIS_AUTH=your-redis-password  # if authentication is enabled

Example Configurations

AWS ElastiCache Redis Cluster

REDIS_CLUSTER_ENABLED=true
REDIS_CLUSTER_NODES=clustercfg.my-redis-cluster.abc123.cache.amazonaws.com:6379
REDIS_AUTH=your-auth-token
REDIS_TLS_ENABLED=true

Self-hosted Redis Cluster

REDIS_CLUSTER_ENABLED=true
REDIS_CLUSTER_NODES=10.0.1.10:6379,10.0.1.11:6379,10.0.1.12:6379,10.0.1.13:6379,10.0.1.14:6379,10.0.1.15:6379
REDIS_AUTH=your-cluster-password

Sizing Recommendations

Langfuse uses Redis mainly for queuing event metadata that should be processed by the worker. In most cases, the worker can process the queue quickly to keep events from piling up. For every ~100000 events per minute we recommend about 1GB of memory for the Redis instance.

Redis Permissions

Redis allows users to restrict the keys and commands that a given user can access Redis ACL Docs. Langfuse expects that the provided user has access to all keys and commands within the given database, i.e. the access control should be defined as on ~* +@all.

Valkey vs Redis

Valkey was created as an open source (BSD) alternative to Redis. It is a drop-in replacement for Redis and is compatible with the Redis protocol. According to the maintainers their major version 8.0.0 retains compatibility to Redis v7 in most instances. We do not extensively test new Langfuse releases with Valkey, but have not encountered any issues in internal experiments using it. Therefore, you can consider Valkey as an option, but you may hit compatibility issues in case its behaviour diverges from Redis.