Redis Client Management#

Overview#

All Redis client creation in Langfuse flows through a single factory function, createNewRedisInstance(), defined in packages/shared/src/server/redis/redis.ts. This function inspects environment variables to dispatch to one of three modes — standalone, cluster, or Sentinel — and accepts per-call additionalOptions to customize connection behavior for each consumer. A global singleton (redis) is also exported for lightweight use cases that don't need a dedicated connection 1.

Connection Modes#

createNewRedisInstance() selects a mode at startup 2:

Cluster and Sentinel modes are mutually exclusive; enabling both returns null with an error log 3.

Default Options#

All instances share defaultRedisOptions:

• enableReadyCheck: true
• maxRetriesPerRequest: null (required for BullMQ)
• keepAlive: 10000 ms — prevents middleboxes from killing idle connections
• socketTimeout: 30000 ms — forces reconnect if no data is received, preventing hung moveToCompleted() from blocking concurrency slots

Queue Retry Strategy#

The exported redisQueueRetryOptions object is passed as additionalOptions by all queue and worker factories. It provides:

• retryStrategy: exponential backoff from 1 s to 20 s, retries forever 4
• reconnectOnError: reconnects on READONLY errors (returns command automatically); ignores MOVED cluster redirects 5

TLS Configuration#

TLS is handled by the shared buildTlsOptions() helper, called inside all three mode constructors. It activates when REDIS_TLS_ENABLED=true and reads certificate/key material from paths (REDIS_TLS_CA_PATH, REDIS_TLS_CERT_PATH, REDIS_TLS_KEY_PATH). Additional TLS knobs: REDIS_TLS_SERVERNAME, REDIS_TLS_REJECT_UNAUTHORIZED, REDIS_TLS_CHECK_SERVER_IDENTITY, REDIS_TLS_CIPHERS, REDIS_TLS_SECURE_PROTOCOL, REDIS_TLS_HONOR_CIPHER_ORDER, REDIS_TLS_KEY_PASSPHRASE. All variables are defined in packages/shared/src/env.ts.

Sentinel Configuration#

createRedisSentinelInstance() requires REDIS_SENTINEL_MASTER_NAME and REDIS_SENTINEL_NODES (comma-separated host:port list). It separates data-node auth (REDIS_AUTH / REDIS_USERNAME) from sentinel-node auth (REDIS_SENTINEL_PASSWORD / REDIS_SENTINEL_USERNAME) 6.

Known issue (v3.167.4+): The sentinel factory does not set sentinelRetryStrategy, causing worker connections to permanently break after a failover. See issue #13880 and KB article: Redis Sentinel Integration for details and workaround.

Cluster Utilities#

When REDIS_CLUSTER_ENABLED=true, three utilities handle cluster constraints:

• getQueuePrefix(): wraps queue key prefixes in Redis hash tags ({prefix:queueName}) so all keys for a queue land on the same hash slot.
• safeMultiDel(): serializes multi-key DEL operations into individual commands to avoid CROSSSLOT errors.
• scanKeys(): fans SCAN operations out to all master nodes in cluster mode.

Per-Service Client Factories#

Every service that owns a queue or needs an isolated Redis connection calls createNewRedisInstance() directly. The most relevant non-queue cases:

RateLimitService (web)#

RateLimitService.getInstance() creates a client with lazyConnect: true — the connection is deferred until the first command is sent. It also disables enableOfflineQueue and enableAutoPipelining (to avoid a known ioredis pipelining issue), and includes redisQueueRetryOptions. Rate limiting is skipped entirely when Redis is unavailable (fail-open) 7.

WorkerManager (worker)#

WorkerManager.register() creates one dedicated Redis connection per registered worker via createNewRedisInstance(redisQueueRetryOptions), giving each BullMQ Worker its own independent connection 8.

BullMQ Queue Singletons#

All queues under packages/shared/src/server/redis/ follow the same static singleton pattern: a lazy getInstance() that creates a BullMQ Queue with a dedicated createNewRedisInstance({ enableOfflineQueue: false, ...redisQueueRetryOptions }) connection 9. Sharded queues (Ingestion, OtelIngestion, TraceUpsert, EvalExecution, LLMAsJudge) maintain a Map of instances keyed by shard index 10.

Global Singleton#

The module-level redis export 1 is a lazily-initialized singleton used by services (e.g., RedisLock) that don't need queue-specific options. In development, it is attached to globalThis to survive hot reloads 11. It is created with only keyPrefix set, via the private createRedisClient() wrapper.

Key Environment Variables#

Full Zod schema: packages/shared/src/env.ts

Primary Source Files#