# CLIENT TRACKING

> Turn server-assisted client-side caching on or off for the connection, so HotKV tells it when a key it read changes.

URL: https://docs.hotkv.com/commands/client-tracking/

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

- Group: Connection
- Complexity: O(N) where N is the number of prefixes
- HotKV Cloud: all plans
- On-Premise: no license needed

`CLIENT TRACKING ON` makes HotKV remember which keys this connection reads, and
send the connection an invalidation when one of them changes. A client can then
keep the values it read in its own memory and drop each one when it is told the
key changed. `OFF` stops it. The [client-side caching guide](https://docs.hotkv.com/develop/client-side-caching/index.md)
explains the model and shows it at work.

## Options

| Option | Effect |
| --- | --- |
| `REDIRECT client-id` | Send the invalidations to the connection with this id (see [CLIENT ID](https://docs.hotkv.com/commands/client-id/index.md)) instead of this one. That connection must exist when the command runs. Needed on a RESP2 connection, which cannot be pushed to. |
| `BCAST` | Tell the client of every key that starts with one of its prefixes, whether it read the key or not. Nothing is remembered per key. |
| `PREFIX prefix` | A key prefix for `BCAST`. Can be repeated. Without a prefix, `BCAST` covers every key. |
| `OPTIN` | Only remember the keys read by a command that comes right after [CLIENT CACHING](https://docs.hotkv.com/commands/client-caching/index.md) `YES`. |
| `OPTOUT` | Remember the keys of every read except a command that comes right after `CLIENT CACHING NO`. |
| `NOLOOP` | Leave out the changes made by this connection's own commands. |

Rules:

- `PREFIX` needs `BCAST`.
- `BCAST` cannot be combined with `OPTIN` or `OPTOUT`, and `OPTIN` cannot be
  combined with `OPTOUT`.
- The prefixes of one client must not overlap: a prefix that starts with another,
  or the same prefix twice, is refused.
- While tracking is on, `BCAST` cannot be switched on or off, and `OPTIN` and
  `OPTOUT` cannot be switched for each other. Turn tracking off first.
- `CLIENT TRACKING ON` on a connection that already tracks replaces its redirect
  and options (and clears a broken redirect) and adds any new prefixes. Asking
  for `BCAST` with no prefix adds the empty prefix, which covers every key, even
  to a client that had other prefixes.
- A connection stops tracking with `OFF`, with [RESET](https://docs.hotkv.com/commands/reset/index.md), or when
  it closes.

## Return value

Simple string `OK`, in RESP2 and RESP3. The invalidations come later, as pushes
on a RESP3 connection, or as messages on `__redis__:invalidate` on a connection
a RESP2 client redirects to.

Errors:

| Error | Cause |
| --- | --- |
| `ERR syntax error` | An unknown option, or something other than `ON` or `OFF` where it belongs. |
| `ERR wrong number of arguments for 'client\|tracking' command` | Nothing after `CLIENT TRACKING`. |
| `ERR value is not an integer or out of range` | The `REDIRECT` id is not an integer. |
| `ERR The client ID you want redirect to does not exist` | No connection has that id. |
| `ERR A client can only redirect to a single other client` | `REDIRECT` was given twice. |
| `ERR PREFIX option requires BCAST mode to be enabled` | `PREFIX` without `BCAST`. |
| `ERR OPTIN and OPTOUT are not compatible with BCAST` | `BCAST` with `OPTIN` or `OPTOUT`. |
| `ERR You can't specify both OPTIN mode and OPTOUT mode` | Both given. |
| `ERR You can't switch BCAST mode on/off before disabling tracking for this client, and then re-enabling it with a different mode.` | `BCAST` differs from the mode tracking is already in. |
| `ERR You can't switch OPTIN/OPTOUT mode before disabling tracking for this client, and then re-enabling it with a different mode.` | `OPTIN` or `OPTOUT` differs from the one already on. |
| `ERR Prefix 'a:' overlaps with another provided prefix 'a:b:'. Prefixes for a single client must not overlap.` | Two prefixes in the command overlap. The text names both. |
| `ERR Prefix 'user:x' overlaps with an existing prefix 'user:'. Prefixes for a single client must not overlap.` | A prefix overlaps one the client already has. |

## Examples

A RESP3 connection, told of a change:

```
# Connection A (after HELLO 3)
127.0.0.1:6379> CLIENT TRACKING ON
OK
127.0.0.1:6379> GET user:1
"alice"

# Connection B
127.0.0.1:6379> SET user:1 bob
OK

# Connection A is sent, without asking:
push> 1) "invalidate"
      2) 1) "user:1"
```

Broadcasting two prefixes, and what the options refuse:

```
127.0.0.1:6379> CLIENT TRACKING ON BCAST PREFIX user: PREFIX order:
OK
127.0.0.1:6379> CLIENT TRACKING ON BCAST PREFIX user:x
(error) ERR Prefix 'user:x' overlaps with an existing prefix 'user:'. Prefixes for a single client must not overlap.
127.0.0.1:6379> CLIENT TRACKING ON
(error) ERR You can't switch BCAST mode on/off before disabling tracking for this client, and then re-enabling it with a different mode.
127.0.0.1:6379> CLIENT TRACKING OFF
OK
127.0.0.1:6379> CLIENT TRACKING ON PREFIX a:
(error) ERR PREFIX option requires BCAST mode to be enabled
```

A RESP2 connection redirecting to a subscriber (connection 52):

```
127.0.0.1:6379> CLIENT TRACKING ON REDIRECT 52
OK
```

## Compatibility

The options, replies and error texts follow Redis 8 and Valkey 9. Tracking is
per node; see the
[guide](https://docs.hotkv.com/develop/client-side-caching/index.md#in-a-cluster-and-on-replicas) for clusters
and replicas.

## See also

[CLIENT CACHING](https://docs.hotkv.com/commands/client-caching/index.md),
[CLIENT TRACKINGINFO](https://docs.hotkv.com/commands/client-trackinginfo/index.md),
[CLIENT GETREDIR](https://docs.hotkv.com/commands/client-getredir/index.md),
[CLIENT ID](https://docs.hotkv.com/commands/client-id/index.md),
[Client-side caching](https://docs.hotkv.com/develop/client-side-caching/index.md)