Skip to content
HotKVDocs

Ask the HotKV docs

Answers come only from these docs and can be wrong; check the linked pages before you rely on them.

LLMSTATS.RECORD

Last updated 
LLMSTATS.RECORD name input_tokens output_tokens cached_tokens cost_usd latency_ms [ERROR 0 | 1] [MODEL model] [CACHEWRITE5M n] [CACHEWRITE1H n]
Group
LLM usage and budgets
Complexity
O(1)
Arity
-7 (at least 7 words, counting the command name)
Flags
write, fast
Keys
first 1, last 1, step 1
HotKV Cloud
Performance and Scale
On-Premise
requires the llm-stats license feature

LLM usage stats keep running totals of the requests, tokens, cost and latency of your model calls in named buckets, for example one per tenant or per model. LLMSTATS.RECORD adds one request to bucket name, creating the bucket if it does not exist.

The positional arguments are:

  • input_tokens: uncached input tokens.
  • output_tokens: output tokens.
  • cached_tokens: tokens read from the provider’s prompt cache.
  • cost_usd: the request’s cost in US dollars. It is used only when you do not pass MODEL; with MODEL, pass 0.
  • latency_ms: the request’s latency in milliseconds.

All token counts and the latency are non-negative integers; cost_usd is a non-negative number.

Options

Section titled “Options”
Option Effect
ERROR 0 or ERROR 1 1 (any non-zero value) counts the request as failed. Default 0.
MODEL model Compute the cost from the shared price table (see LLMSTATS.PRICE) using all the token counts given, instead of cost_usd. If the model has no price, the request still counts its tokens, adds nothing to the cost and increments unpriced_requests.
CACHEWRITE5M n Tokens written to a 5-minute provider cache.
CACHEWRITE1H n Tokens written to a 1-hour provider cache.

Options follow the positional arguments in name and value pairs, in any order.

Providers count tokens differently. Anthropic reports uncached input, cache-read and cache-write tokens separately, which map straight onto these arguments. OpenAI’s prompt token count includes the cached tokens, so subtract cached_tokens from it before you pass it as input_tokens with MODEL.

Return value

Section titled “Return value”
Case RESP2 RESP3
Request recorded Simple string OK Same

Errors:

  • ERR invalid numeric argument if a positional count is not a non-negative integer, or cost_usd is negative or not a number.
  • ERR invalid ERROR flag, ERR invalid CACHEWRITE5M or ERR invalid CACHEWRITE1H if an option value is not a non-negative integer.
  • ERR syntax error if an option has no value.
  • ERR unknown option for any other option name.
  • ERR bucket limit reached if the bucket is new and the server already holds its maximum number of buckets.
  • ERR wrong number of arguments for 'llmstats.record' command if the argument count is wrong.
  • NOLICENSE llm-stats requires a HotKV license. Contact sales@hotkv.com if your license does not include the llm-stats feature.

Examples

Section titled “Examples”
127.0.0.1:6379> LLMSTATS.RECORD model_sonnet5 100000 2000 50000 0 420 MODEL claude-sonnet-5 CACHEWRITE5M 10000
OK
127.0.0.1:6379> LLMSTATS.RECORD self_hosted 1200 300 0 0.0042 95
OK
127.0.0.1:6379> LLMSTATS.RECORD self_hosted 900 0 0 0 30000 ERROR 1
OK

The first call is priced from the built-in claude-sonnet-5 price; the second records a cost you computed yourself.

Compatibility

Section titled “Compatibility”

HotKV-only command. Redis and Valkey have no equivalent.

See also

Section titled “See also”

LLMSTATS.BUCKET, LLMSTATS.GET, LLMSTATS.RESET, LLMSTATS.DROP, LLMSTATS.LIST, LLMSTATS.PRICE, LLMBUDGET.CONSUME, AI features guide