Implementation:Langfuse Langfuse Redis Client

Knowledge Sources	Langfuse
Domains	Infrastructure, Caching, Queue
Last Updated	2026-02-14 00:00 GMT

Overview

Provides a singleton Redis client factory supporting standalone, cluster, and sentinel deployment modes with TLS configuration, used across Langfuse for caching and BullMQ job queues.

Description

This module is the central Redis connection management layer for the Langfuse platform. It abstracts the creation of Redis connections behind a unified factory function (createNewRedisInstance) that automatically selects the correct connection mode based on environment variables: standalone (single node via connection string or host/port), Redis Cluster (via REDIS_CLUSTER_NODES), or Redis Sentinel (via REDIS_SENTINEL_NODES). The module ensures that cluster and sentinel modes are mutually exclusive.

Key capabilities include:

• TLS support -- Reads TLS certificates, keys, CA files, and related options from environment variables to build secure Redis connections.
• Retry strategies -- Exports redisQueueRetryOptions with exponential backoff (1s to 20s) and automatic reconnection on READONLY errors (useful for failover scenarios).
• Cluster-safe operations -- Provides safeMultiDel to delete keys without CROSSSLOT errors in cluster mode, and scanKeys to scan across all master nodes.
• Queue prefix management -- getQueuePrefix returns hash-tagged prefixes for BullMQ compatibility in cluster mode, ensuring all queue keys land on the same hash slot.
• Singleton pattern -- A global redis instance is exported and cached on globalThis in non-production environments to survive hot-module reloads during development.

Usage

Use this module whenever you need a Redis connection in Langfuse server-side code. Import the singleton redis for general-purpose caching and key operations. Use createNewRedisInstance when you need a dedicated connection (e.g., for BullMQ workers that require their own connection). Use getQueuePrefix when creating BullMQ queues to ensure cluster compatibility.

Code Reference

Source Location

• Repository: Langfuse
• File: packages/shared/src/server/redis/redis.ts
• Lines: 1-313

Signature

export const redisQueueRetryOptions: Partial<RedisOptions>;

export const createNewRedisInstance = (
  additionalOptions?: Partial<RedisOptions>,
): Redis | Cluster | null;

export const getQueuePrefix = (queueName: string): string | undefined;

export const safeMultiDel = async (
  redis: Redis | Cluster | null,
  keys: string[],
): Promise<void>;

export const scanKeys = async (
  redis: Redis | Cluster | null,
  pattern: string,
): Promise<string[]>;

export const redis: Redis | Cluster | null;

Import

import {
  redis,
  createNewRedisInstance,
  redisQueueRetryOptions,
  getQueuePrefix,
  safeMultiDel,
  scanKeys,
} from "@langfuse/shared/src/server/redis/redis";

I/O Contract

Inputs

Name	Type	Required	Description
additionalOptions	Partial<RedisOptions>	No	Extra ioredis options merged into default configuration
queueName	string	Yes (for getQueuePrefix)	BullMQ queue name used to generate hash-tagged prefix
keys	string[]	Yes (for safeMultiDel)	Redis keys to delete
pattern	string	Yes (for scanKeys)	Glob pattern for SCAN command (e.g. "cache:*")

Outputs

Name	Type	Description
redis	Cluster | null	Singleton Redis client instance; null if Redis is not configured
createNewRedisInstance return	Cluster | null	New Redis/Cluster connection or null on failure
getQueuePrefix return	undefined	Hash-tagged prefix like "{queueName}" in cluster mode, undefined otherwise
scanKeys return	Promise<string[]>	Collected keys matching the pattern across all nodes

Usage Examples

import { redis, createNewRedisInstance, redisQueueRetryOptions, getQueuePrefix } from "@langfuse/shared/src/server/redis/redis";

// Use the singleton for caching
if (redis) {
  await redis.set("myKey", "myValue", "EX", 300);
  const value = await redis.get("myKey");
}

// Create a dedicated connection for a BullMQ worker
const workerConnection = createNewRedisInstance(redisQueueRetryOptions);

// Get cluster-safe prefix for a BullMQ queue
const prefix = getQueuePrefix("ingestion-queue");
// In cluster mode: "{ingestion-queue}", otherwise: undefined

Related Pages

• Environment:Langfuse_Langfuse_Redis_7_Queue_Cache