client-tracking.3valkey - Man Page

CLIENT TRACKING <ON | OFF> [REDIRECT client-id] [PREFIX prefix [PREFIX prefix ...]] [BCAST] [OPTIN] [OPTOUT] [NOLOOP]

This command enables the tracking feature of the Valkey server, that is used for valkey-client-side-caching(7) server assisted client side caching.

When tracking is enabled Valkey 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 (only available when the RESP3 protocol is used) or redirected in a different connection (available also with RESP2 and Pub/Sub). A special broadcasting mode is available where clients participating in this protocol receive every notification just subscribing to given key prefixes, regardless of the keys that they requested. Given the complexity of the argument please refer to valkey-client-side-caching(7) the main client side caching documentation for the details. This manual page is only a reference for the options of this subcommand.

In order to enable tracking, use:

CLIENT TRACKING on ... options ...

The feature will remain active in the current connection for all its life, unless tracking is turned off with CLIENT TRACKING off at some point.

The following are the list of options that modify the behavior of the command when enabling tracking:

• REDIRECT <id>: send invalidation messages to the connection with the specified ID. The connection must exist. You can get the ID of a connection using CLIENT ID. If the connection we are redirecting to is terminated, when in RESP3 mode the connection with tracking enabled will receive tracking-redir-broken push messages in order to signal the condition.
• BCAST: enable tracking in broadcasting mode. In this mode invalidation messages are reported for all the prefixes specified, regardless of the keys requested by the connection. Instead when the broadcasting mode is not enabled, Valkey will track which keys are fetched using read-only commands, and will report invalidation messages only for such keys.
• PREFIX <prefix>: for broadcasting, register a given key prefix, so that notifications will be provided only for keys starting with this string. This option can be given multiple times to register multiple prefixes. If broadcasting is enabled without this option, Valkey will send notifications for every key. You can’t delete a single prefix, but you can delete all prefixes by disabling and re-enabling tracking. Using this option adds the additional time complexity of O(N^2), where N is the total number of prefixes tracked.
• OPTIN: when broadcasting is NOT active, normally don’t track keys in read only commands, unless they are called immediately after a CLIENT CACHING yes command.
• OPTOUT: when broadcasting is NOT active, normally track keys in read only commands, unless they are called immediately after a CLIENT CACHING no command.
• NOLOOP: don’t send notifications about keys modified by this connection itself.

valkey-protocol(7) 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.

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

@connection @slow

• Available since: 6.0.0

auth(3valkey), client(3valkey), client-caching(3valkey), client-capa(3valkey), client-getname(3valkey), client-getredir(3valkey), client-help(3valkey), client-id(3valkey), client-info(3valkey), client-kill(3valkey), client-list(3valkey), client-no-evict(3valkey), client-no-touch(3valkey), client-pause(3valkey), client-reply(3valkey), client-setinfo(3valkey), client-setname(3valkey), client-trackinginfo(3valkey), client-unblock(3valkey), client-unpause(3valkey), echo(3valkey), hello(3valkey), ping(3valkey), reset(3valkey), select(3valkey)