Keyspace notifications

Active contributors: antirez, Oran Agra, Wen Hui.

Purpose

When notify-keyspace-events <flags> is enabled, the server publishes a Pub/Sub message every time a key is created, modified, expired, evicted, or otherwise affected. Two channels per event:

• __keyspace@<dbid>__:<key> — the message payload is the event name.
• __keyevent@<dbid>__:<event> — the message payload is the key name.

Subscribers can listen on either depending on what they want to filter on.

Source layout

File	Role
src/notify.c	notifyKeyspaceEvent, the flag parser, the channel emission.
Type implementations	Each t_*.c calls notifyKeyspaceEvent after a successful mutation.
src/expire.c, src/evict.c, src/lazyfree.c	Emit expired, evicted, and del events respectively.

Configuration

notify-keyspace-events takes a flag string. Each letter enables a class:

Letter	Class	Examples
K	Keyspace channel (__keyspace@<db>__)	(toggle, no events of its own)
E	Keyevent channel (__keyevent@<db>__)	(toggle)
g	Generic	del, expire, rename, move, copy
$	String	set, setrange, incrby
l	List	lpush, rpop, lset
s	Set	sadd, srem, spop
h	Hash	hset, hdel, hincrby
z	Sorted set	zadd, zrem, zincrby
t	Stream	xadd, xdel, xtrim
x	Expiration	expired (fired on TTL elapse)
e	Eviction	evicted (fired by maxmemory eviction)
n	Key-miss	keymiss (fired on access of a non-existent key, RESP3 push)
d	Module	Module-defined types via RedisModule_NotifyKeyspaceEvent
m	Move-expired	When a key is migrated and was already expired on the source.
A	Alias for g$lshzxet	Convenient shorthand.

To enable everything: notify-keyspace-events AKE.

By default the option is empty — no notifications fire — to avoid the overhead in deployments that don't need them.

Performance characteristics

Each event = one PUBLISH call. With notify-keyspace-events AKE and a workload of 100k commands/sec, each command produces 1–2 publishes ⇒ 100–200k publishes/sec. The Pub/Sub fan-out is O(subscribers). If no one is subscribed, the cost is a dict lookup on the channel name and an early return — cheap but not free.

For high-throughput dashboards the recommendation is to subscribe to __keyevent@*__:expired (or whichever specific event you need) rather than the firehose, and to scope subscribers to the smallest pattern.

Patterns

A common idiom: subscribe to __keyevent@0__:expired to react to TTL expirations in DB 0. Useful for cache-invalidation use cases:

PSUBSCRIBE __keyevent@0__:expired

The published messages are key names. Combine with EXPIRE on a worker job key to get a "scheduled task" pattern.

Replication

Notifications are not replicated. A subscriber on a replica only sees events for changes that actually happen on that replica (mostly the master's command stream replayed plus locally-generated expired/evicted events that the replica itself runs — see below).

Replicas don't run their own active expiration; expirations on a replica come as DEL commands from the master. Whether the replica re-emits expired or treats them as plain deletes is controlled by replica-lazy-flush and related options.

Cluster

In cluster mode notifications are local to the node where the change happens. Other nodes don't see them. Sharded Pub/Sub does not change this — notifications use the regular (non-sharded) Pub/Sub fan-out.

Adding a new notification

If you implement a new mutating command, fire a notification at the end of the handler:

notifyKeyspaceEvent(NOTIFY_GENERIC, "myop", c->argv[1], c->db->id);

The NOTIFY_* flags are in src/server.h. The full set: NOTIFY_GENERIC, NOTIFY_STRING, NOTIFY_LIST, NOTIFY_SET, NOTIFY_HASH, NOTIFY_ZSET, NOTIFY_STREAM, NOTIFY_EXPIRED, NOTIFY_EVICTED, NOTIFY_NEW_KEY, NOTIFY_KEYMISS, NOTIFY_MODULE.

The flag is matched against server.notify_keyspace_events; if disabled, the call is a no-op.

RESP3 invalidation pushes

A related but different mechanism: when a client uses CLIENT TRACKING ON (server-assisted client-side caching), the server sends RESP3 push frames named invalidate to that client when watched keys change. These are not the same as keyspace notifications — they go directly to the client over its own connection (or a designated redirect connection in RESP2 mode), not via Pub/Sub. See Pub/Sub & tracking.

Related pages

• Pub/Sub & tracking — the underlying delivery mechanism.
• Expiration — the source of expired events.
• Memory management — evicted events come from here.