Twemproxy — Fast Lightweight Proxy for Memcached and Redis

Introduction

Twemproxy (also called nutcracker) is a proxy created by Twitter to sit between application clients and pools of Memcached or Redis servers. It multiplexes thousands of client connections into a small number of backend connections, reducing resource usage while automatically distributing keys across shards.

What Twemproxy Does

• Proxies requests to multiple Memcached or Redis instances transparently
• Automatically shards data using consistent hashing or other distribution strategies
• Multiplexes many client connections into fewer backend connections to reduce load
• Detects failed backends and temporarily ejects them from the pool
• Supports pipelining of requests and responses for higher throughput

Architecture Overview

Twemproxy runs as a single-threaded event-driven process using epoll or kqueue. Incoming client connections are accepted on a listening socket and each request is parsed, hashed to a backend server, and forwarded. Responses travel back through the same proxy connection. The consistent hashing ring can be configured with ketama, modula, or random distribution modes.

Self-Hosting & Configuration

• Build from source using autoconf and make, or install via package managers on some distributions
• Define server pools in a YAML configuration file specifying listen address, hash function, and backend list
• Set the hash algorithm (fnv1a_64, murmur, md5, crc32, etc.) and distribution mode (ketama, modula, random)
• Configure server_retry_timeout and server_failure_limit to control automatic ejection of unhealthy backends
• Enable stats collection on a dedicated port for monitoring via tools like collectd or Prometheus exporters

Key Features

• Extremely low overhead with single-threaded epoll-based architecture
• Zero-copy proxying keeps latency minimal even at high throughput
• Supports both Memcached ASCII and Redis protocols in the same binary
• Connection multiplexing reduces the total number of TCP connections to backends
• Production-proven at Twitter-scale handling millions of requests per second

Comparison with Similar Tools

• Redis Cluster — Native sharding built into Redis, but requires Redis 3.0+ and cluster-aware clients
• ProxySQL — Focused on MySQL protocol proxying, not cache stores
• Envoy — General-purpose L4/L7 proxy that can front Redis, but heavier and more complex
• mcrouter — Meta's Memcached proxy with richer routing, but Memcached-only
• KeyDB — Multi-threaded Redis fork with built-in active replication, but not a proxy

FAQ

Q: Does Twemproxy support Redis Cluster commands? A: No. Twemproxy predates Redis Cluster and implements its own sharding. Multi-key commands that span shards are not supported.

Q: Can Twemproxy handle Redis Pub/Sub? A: No. Pub/Sub, blocking commands, and scripting are not proxied because they require stateful server affinity.

Q: How does Twemproxy handle a backend going down? A: It ejects the server from the hash ring after a configurable number of failures and re-adds it after a timeout.

Q: Is Twemproxy still maintained? A: The repository receives occasional updates. It remains widely deployed in production but new features are infrequent.

Sources

• https://github.com/twitter/twemproxy
• https://github.com/twitter/twemproxy/blob/master/notes/recommendation.md