CLIENT TRACKING

Syntax

  1. CLIENT TRACKING <ON | OFF> [OPTIN] [OPTOUT] [NOLOOP]

Time complexity: O(1). Some options may introduce additional complexity.

ACL categories: @slow, @connection

Important: New in Dragonfly v1.14, only available when the RESP3 protocol is used.

The CLIENT TRACKING command enables the tracking feature of the Dragonfly server, which is used for server-assisted client side caching. See more details about server-assisted client side caching in the Redis documentation.

When tracking is enabled, Dragonfly remembers the keys that the connection requested in order to send later invalidation messages when such keys are modified. Invalidation messages are sent in the same connection when the RESP3 protocol is used. It is very important to note that only when the client reads a key after enabling tracking will Dragonfly start tracking that key. Solely creating a key will not make Dragonfly track the key. See the examples below for more details.

The feature will remain active in the current connection for all its life, unless tracking is disabled with CLIENT TRACKING OFF at some point, and Dragonfly stops tracking the keys for the connection, and no invalidation messages are sent.

Return

Simple string reply: OK if the connection was successfully put in tracking mode or if the tracking mode was successfully disabled. Otherwise, an error is returned.

Options

OPTIN: Do not track keys for read only commands unless they are called immediately after a CLIENT CACHING YES command.

OPTOUT: Track keys in read only commands unless they are called immediately after a CLIENT CACHING NO command.

NOLOOP: Do not send notifications for keys modified by the current connection itself.

Examples

Use two clients to connect to the Dragonfly server using the RESP3 protocol. Switching to the RESP3 protocol can be done with the HELLO command. Alternatively, clients or SDKs may have a configuration option to use the RESP3 protocol (i.e., redis-cli -3) upon connection.

In the example below, client-1 is put in tracking mode. Note that creating a non-existing key will not make Dragonfly track the key. Instead, the key must be read after tracking is enabled to start being tracked.

  1. ### client-1 ###
  3. # Switch protocol to RESP3, output omitted.
  4. dragonfly> HELLO 3
  6. # Switch on client tracking.
  7. dragonfly> CLIENT TRACKING ON
  8. OK
  10. # Create a key and set its value to 100.
  11. dragonfly> SET user_count 100
  12. OK
  14. # Read the key so that the server starts tracking its update.
  15. dragonfly> GET user_count
  16. "100"

Now client-2 makes an update on the key:

  1. ### client-2 ###
  3. # Now client-2 updates the value.
  4. dragonfly> INCR user_count
  5. (integer) 101

Back to client-1 again, it reads the key (within the same session) and receives an invalidation message on the key:

  1. ### client-1 ###
  3. # After client-2 updates the value,
  4. # client-1 reads the key again and receives an invalidation message.
  5. dragonfly> GET user_count
  6. -> invalidate: 'user_count'
  7. "101"