CLIENT-TRACKING(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

🎀 NAME 🎀

okay so this is the CLIENT-TRACKING page from the Valkey Command Manual (the 3valkey girlies know) and it's literally all about controlling server-assisted client-side caching for your connection. no cap. 💅

✨ SYNOPSIS ✨

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

🦋 DESCRIPTION 🦋

bestie. listen. this command turns on the tracking feature of the Valkey server, and that whole feature exists to power valkey-client-side-caching(7) — the server assisted client side caching situation. it's giving "your server is doing the memory work for you". iconic behavior honestly.

so here's the vibe: when tracking is on, Valkey remembers the keys that your connection asked for, so that later it can slide invalidation messages into your DMs when those keys get modified. 💌

those invalidation messages can go two ways:

  • sent on the same connection — but only when the RESP3 protocol is being used, so if you're on RESP2 this door is locked, sorry babe 🙈
  • redirected to a different connection — and this one works with RESP2 and Pub/Sub too 🎉

there's also a special broadcasting mode where clients in this protocol receive every notification, just by subscribing to given key prefixes, regardless of which keys they actually requested. so you're not tracking your own reads, you're just vibing on a prefix.

lowkey the arguments here get complicated, so fr fr go read valkey-client-side-caching(7), the main client side caching documentation, for the full details. this manual page is ONLY a reference for the options of this subcommand. it is not the whole story, it's the highlight reel. ⭐

to enable tracking, you do:

CLIENT TRACKING on ... options ...

and heads up: the feature will stay active in the current connection for all its life, unless tracking gets turned off with CLIENT TRACKING off at some point. so it's a forever thing until it's not. 💀

here's the list of options that modify the behavior of the command when you're enabling tracking:

  • REDIRECT <id> — send invalidation messages to the connection with the specified ID. that connection must exist. you can get the ID of a connection using valkey-client-id(7) CLIENT ID. and if the connection you're redirecting to gets terminated? when in RESP3 mode, the connection with tracking enabled will receive tracking-redir-broken push messages to signal the condition. so you'll know. 👀
  • BCAST — enable tracking in broadcasting mode. in this mode, invalidation messages get reported for all the prefixes specified, regardless of the keys requested by the connection. meanwhile, when 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. two totally different energies. ✨
  • PREFIX <prefix> — for broadcasting, register a given key prefix, so notifications get 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. 🫶
warning bestie: you can't delete a single prefix, but you can delete all prefixes by disabling and re-enabling tracking. also, using this option adds the additional time complexity of O(N^2), where N is the total number of prefixes tracked. yes, N squared. it's giving "cost of doing business". 😭
  • OPTIN — when broadcasting is NOT active: normally don't track keys in read only commands, unless they are called immediately after a valkey-client-caching(7) CLIENT CACHING yes command. opt-in only, queen. 💅
  • OPTOUT — when broadcasting is NOT active: normally track keys in read only commands, unless they are called immediately after a CLIENT CACHING no command. you're in by default but you can dip out. 🙈
  • NOLOOP — don't send notifications about keys modified by this connection itself. like, don't text me about my own drama. 🚫

💬 REPLY 💬

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. so it's either slay or nope. ✨

🔥 COMPLEXITY 🔥

O(1). but some options may introduce additional complexity. (looking at you, PREFIX. 👀)

👑 ACL CATEGORIES 👑

@connection @slow

🌈 HISTORY 🌈

  1. Available since: 6.0.0

🫶 SEE ALSO 🫶

go read your sisters, they're all connected:

and that's the whole page bestie, no crumbs left. this was Valkey version 9.0.0, dated 2025-10-21 — go forth and cache client-side, you absolute icon. 💖✨🎀🦋🌸💅🫶

📦 where this page comes from