Redis Keyspace Notifications

IMPORTANT Keyspace notifications is a feature available since 2.8.0

Keyspace notifications allows clients to subscribe to Pub/Sub channels in order to receive events affecting the Redis data set in some way.

Examples of the events that is possible to receive are the following:

All the commands affecting a given key.

All the keys receiving an LPUSH operation.

All the keys expiring in the database 0.

Events are delivered using the normal Pub/Sub layer of Redis, so clients implementing Pub/Sub are able to use this feature without modifications.

Because Redis Pub/Sub is fire and forget currently there is no way to use this feature if you application demands reliable notification of events, that is, if your Pub/Sub client disconnects, and reconnects later, all the events delivered during the time the client was disconnected are lost.

In the future there are plans to allow for more reliable delivering of events, but probably this will be addressed at a more general level either bringing reliability to Pub/Sub itself, or allowing Lua scripts to intercept Pub/Sub messages to perform operations like pushing the events into a list.

Keyspace notifications are implemented sending two distinct type of events for every operation affecting the Redis data space. For instance a <code>DEL</code> operation targeting the key named <code>mykey</code> in database <code>0</code> will trigger the delivering of two messages, exactly equivalent to the following two <code>PUBLISH</code> commands:

It is easy to see how one channel allows to listen to all the events targeting the key <code>mykey</code> and the other channel allows to obtain information about all the keys that are target of a <code>del</code> operation.

The first kind of event, with <code>keyspace</code> prefix in the channel is called a Key-space notification, while the second, with the <code>keyevent</code> prefix, is called a Key-event notification.

In the above example a <code>del</code> event was generated for the key <code>mykey</code>. What happens is that:

The Key-space channel receives as message the name of the event.

The Key-event channel receives as message the name of the key.

It is possible to enable only one kind of notification in order to deliver just the subset of events we are interested in.

By default keyspace events notifications are disabled because while not very sensible the feature uses some CPU power. Notifications are enabled using the <code>notify-keyspace-events</code> of redis.conf or via the CONFIG SET.

Setting the parameter to the empty string disables notifications. In order to enable the feature a non-empty string is used, composed of multiple characters, where every character has a special meaning according to the following table:

At least <code>K</code> or <code>E</code> should be present in the string, otherwise no event will be delivered regardless of the rest of the string.

For instance to enable just Key-space events for lists, the configuration parameter must be set to <code>Kl</code>, and so forth.

The string <code>KEA</code> can be used to enable every possible event.

Different commands generate different kind of events according to the following list.

<code>DEL</code> generates a <code>del</code> event for every deleted key.

<code>RENAME</code> generates two events, a <code>rename_from</code> event for the source key, and a <code>rename_to</code> event for the destination key.

<code>EXPIRE</code> generates an <code>expire</code> event when an expire is set to the key, or a <code>expired</code> event every time setting an expire results into the key being deleted (see <code>EXPIRE</code> documentation for more info).

<code>SORT</code> generates a <code>sortstore</code> event when <code>STORE</code> is used to set a new key. If the resulting list is empty, and the <code>STORE</code> option is used, and there was already an existing key with that name, the result is that the key is deleted, so a <code>del</code> event is generated in this condition.

<code>SET</code> and all its variants (<code>SETEX</code>, <code>SETNX</code>,<code>GETSET</code>) generate <code>set</code> events. However <code>SETEX</code> will also generate an <code>expire</code> events.

<code>MSET</code> generates a separated <code>set</code> event for every key.

<code>SETRANGE</code> generates a <code>setrange</code> event.

<code>INCR</code>, <code>DECR</code>, <code>INCRBY</code>, <code>DECRBY</code> commands all generate <code>incrby</code> events.

<code>INCRBYFLOAT</code> generates an <code>incrbyfloat</code> events.

<code>APPEND</code> generates an <code>append</code> event.

<code>LPUSH</code> and <code>LPUSHX</code> generates a single <code>lpush</code> event, even in the variadic case.

<code>RPUSH</code> and <code>RPUSHX</code> generates a single <code>rpush</code> event, even in the variadic case.

<code>RPOP</code> generates an <code>rpop</code> event. Additionally a <code>del</code> event is generated if the key is removed because the last element from the list was popped.

<code>LPOP</code> generates an <code>lpop</code> event. Additionally a <code>del</code> event is generated if the key is removed because the last element from the list was popped.

<code>LINSERT</code> generates an <code>linsert</code> event.

<code>LSET</code> generates an <code>lset</code> event.

<code>LTRIM</code> generates an <code>ltrim</code> event, and additionally a <code>del</code> event if the resulting list is empty and the key is removed.

<code>RPOPLPUSH</code> and <code>BRPOPLPUSH</code> generate an <code>rpop</code> event and an <code>lpush</code> event. In both cases the order is guaranteed (the <code>lpush</code>event will always be delivered after the <code>rpop</code> event). Additionally a <code>del</code> event will be generated if the resulting list is zero length and the key is removed.

<code>HSET</code>, <code>HSETNX</code> and <code>HMSET</code> all generate a single <code>hset</code> event.

<code>HINCRBY</code> generates an <code>hincrby</code> event.

<code>HINCRBYFLOAT</code> generates an <code>hincrbyfloat</code> event.

<code>HDEL</code> generates a single <code>hdel</code> event, and an additional <code>del</code> event if the resulting hash is empty and the key is removed.

<code>SADD</code> generates a single <code>sadd</code> event, even in the variadic case.

<code>SREM</code> generates a single <code>srem</code> event, and an additional <code>del</code> event if the resulting set is empty and the key is removed.

<code>SMOVE</code> generates an <code>srem</code> event for the source key, and an <code>sadd</code> event for the destination key.

<code>SPOP</code> generates an <code>spop</code> event, and an additional <code>del</code> event if the resulting set is empty and the key is removed.

<code>SINTERSTORE</code>, <code>SUNIONSTORE</code>, <code>SDIFFSTORE</code> generate <code>sinterstore</code>, <code>sunionostore</code>, <code>sdiffstore</code> events respectively. In the special case the resulting set is empty, and the key where the result is stored already exists, a <code>del</code> event is generated since the key is removed.

<code>ZINCR</code> generates a <code>zincr</code> event.

<code>ZADD</code> generates a single <code>zadd</code> event even when multiple elements are added.

<code>ZREM</code> generates a single <code>zrem</code> event even when multiple elements are deleted. When the resulting sorted set is empty and the key is generated, an additional <code>del</code> event is generated.

<code>ZREMBYSCORE</code> generates a single <code>zrembyscore</code> event. When the resulting sorted set is empty and the key is generated, an additional <code>del</code> event is generated.

<code>ZREMBYRANK</code> generates a single <code>zrembyrank</code> event. When the resulting sorted set is empty and the key is generated, an additional <code>del</code> event is generated.

<code>ZINTERSTORE</code> and <code>ZUNIONSTORE</code> respectively generate <code>zinterstore</code> and <code>zunionstore</code> events. In the special case the resulting sorted set is empty, and the key where the result is stored already exists, a <code>del</code> event is generated since the key is removed.

Every time a key with a time to live associated is removed from the data set because it expired, an <code>expired</code> event is generated.

Every time a key is evicted from the data set in order to free memory as a result of the <code>maxmemory</code> policy, an <code>evicted</code>event is generated.

IMPORTANT all the commands generate events only if the target key is really modified. For instance an <code>SREM</code> deleting a non-existing element from a Set will not actually change the value of the key, so no event will be generated.

If in doubt about how events are generated for a given command, the simplest thing to do is to watch yourself:

At this point use <code>redis-cli</code> in another terminal to send commands to the Redis server and watch the events generated:

Keys with a time to live associated are expired by Redis in two ways:

When the key is accessed by a command and is found to be expired.

Via a background system that looks for expired keys in background, incrementally, in order to be able to also collect keys that are never accessed.

The <code>expired</code> events are generated when a key is accessed and is found to be expired by one of the above systems, as a result there are no guarantees that the Redis server will be able to generate the <code>expired</code> event at the time the key time to live reaches the value of zero.

If no command targets the key constantly, and there are many keys with a TTL associated, there can be a significant delay between the time the key time to live drops to zero, and the time the <code>expired</code> event is generated.

Basically <code>expired</code> events are generated when the Redis server deletes the key and not when the time to live theoretically reaches the value of zero.

本文作者：陳群

本文來自雲栖社群合作夥伴rediscn，了解相關資訊可以關注redis.cn網站。