//! LLM 用量统计:按**账号**与按**账号 × 上游**两个维度计数。 //! //! 数据全部躺在共享内存里(`ust:` / `ums:` 两个键前缀),没有新文件、 //! 没有新进程——这是项目「单容器零依赖」红线下的必然选择。 //! //! ```text //! ust: → <日窗id>:<今日数>:<累计数>:<最近调用时间戳> //! ums:: → 同 上 //! ``` //! //! ## 口径:只统计"真的转发出去"的请求 //! //! 计数点在 `LlmHandler` 的**鉴权 / 白名单 / 限流全部通过之后**, //! 所以 401 / 403 / 404 / 429 都不计入。这与配额计数 `st:` 刻意不同—— //! 后者是"先增后判"(含被拒),要的是"超限后计数继续涨"的执行语义; //! 而用量统计是给人看的,把被拒的请求算进"用量"只会让人误解。 //! //! ## token 级计量(2026-09-12 起) //! //! token 数来自上游响应体里的 `usage` 字段:`llm_usage` 模块在 **body filter 链** //! 旁路扫描响应(SSE 尾部 / 非 stream JSON 尾部),零缓冲、不影响透传; //! log 阶段统一入账到 `utt:` / `utms:` 两个键前缀,编码与本文件同款格式。 //! 抓不到 usage(如 OpenAI 流式客户端没带 `include_usage`)= 记 0,不补估。 //! 计数口径与请求数一致:**只算真的转发出去且上游给了 usage 的**。 use std::collections::BTreeMap; use serde_json::{Value, json}; use crate::config::{ KEY_UDAY_PREFIX, KEY_UDAY_SLOT_PREFIX, KEY_UDAY_USER_PREFIX, KEY_UMS_PREFIX, KEY_UTMS_PREFIX, KEY_UST_PREFIX, KEY_UTT_PREFIX, TREND_DAYS_DEFAULT, TREND_DAYS_MAX, TREND_KEEP_SECS, }; use crate::state; use crate::util; /// 一条统计记录的读数。`today` 已按调用方给的日窗折算过(跨天即为 0)。 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] pub struct Usage { /// 今日(本地自然日)请求数 pub today: i64, /// 累计请求数(自该计数键建立以来,不随跨天归零) pub total: i64, /// 最近一次调用时间戳;0 = 从未调用 pub last_ts: i64, } impl Usage { /// 累加(聚合用)。`last_ts` 取最大。 fn merge(&mut self, other: &Usage) { self.today += other.today; self.total += other.total; if other.last_ts > self.last_ts { self.last_ts = other.last_ts; } } pub fn json(&self) -> Value { json!({ "today": self.today, "total": self.total, "last_ts": self.last_ts, "last_ts_text": if self.last_ts > 0 { util::fmt_time(self.last_ts) } else { String::new() }, }) } } /// token 计量读数。日窗语义与 [`Usage`] 相同:跨天 today 归零、累计保留。 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] pub struct TokenUsage { /// 今日入 token(prompt / input) pub tin_today: i64, /// 累计入 token pub tin_total: i64, /// 今日出 token(completion / output) pub tout_today: i64, /// 累计出 token pub tout_total: i64, /// 最近一次有 token 记账的调用时间戳;0 = 从未 pub last_ts: i64, } impl TokenUsage { /// 累加(聚合用)。`last_ts` 取最大。 fn merge(&mut self, other: &TokenUsage) { self.tin_today += other.tin_today; self.tin_total += other.tin_total; self.tout_today += other.tout_today; self.tout_total += other.tout_total; if other.last_ts > self.last_ts { self.last_ts = other.last_ts; } } pub fn json(&self) -> Value { json!({ "in_today": self.tin_today, "in_total": self.tin_total, "out_today": self.tout_today, "out_total": self.tout_total, "last_ts": self.last_ts, "last_ts_text": if self.last_ts > 0 { util::fmt_time(self.last_ts) } else { String::new() }, }) } } /// 一个账号的用量 + 其下每个上游的明细 pub struct UserUsage { pub username: String, pub usage: Usage, pub models: Vec<(String, Usage)>, } /// 一个上游的用量 + 用它的每个账号的明细 pub struct ModelUsage { pub slot: String, pub usage: Usage, pub users: Vec<(String, Usage)>, } // =========================================================================== // 编解码 // =========================================================================== /// `<日窗id>:<今日数>:<累计数>:<最近调用时间戳>`。 /// 字段全是数字,用 `:` 分隔不会与键名里的字符冲突(键不参与这段编码)。 fn encode(day: i64, u: &Usage) -> String { format!("{}:{}:{}:{}", day, u.today, u.total, u.last_ts) } /// 解码并把"今日数"按当前日窗折算——跨天时旧值归零,累计值保留。 fn decode(payload: &str, day: i64) -> Usage { let mut it = payload.split(':'); let stored_day = it.next().and_then(|s| s.parse::().ok()).unwrap_or(0); let today = it.next().and_then(|s| s.parse::().ok()).unwrap_or(0); let total = it.next().and_then(|s| s.parse::().ok()).unwrap_or(0); let last_ts = it.next().and_then(|s| s.parse::().ok()).unwrap_or(0); Usage { today: if stored_day == day { today } else { 0 }, total, last_ts } } fn bump(prefix: &[u8], name: &str, day: i64, now: i64) { let current = state::get(prefix, name.as_bytes()) .map(|(payload, _)| decode(&payload, day)) .unwrap_or_default(); let next = Usage { today: current.today + 1, total: current.total + 1, last_ts: now, }; // 与限流的窗口计数同款近似语义:读-增-写不加写锁(并发下偶发少计一次), // 换来的是 LLM 热路径不为统计去抢锁。统计用途下这点误差无影响。 state::put(prefix, name.as_bytes(), encode(day, &next).as_bytes(), 0); } // =========================================================================== // 写 // =========================================================================== /// 记录一次已放行的 LLM 请求。**在鉴权/白名单/限流全通过之后调用**。 pub fn record(username: &str, slot: &str, now: i64) { if username.is_empty() || slot.is_empty() { return; } let day = util::day_id(now); bump(KEY_UST_PREFIX, username, day, now); bump(KEY_UMS_PREFIX, &format!("{username}:{slot}"), day, now); // 日桶:趋势图数据源(请求维度)。三个维度各写一次,键名带日窗 id let delta = DayBucket { requests: 1, ..Default::default() }; bump_day(KEY_UDAY_PREFIX, &day.to_string(), &delta); bump_day(KEY_UDAY_USER_PREFIX, &format!("{username}:{day}"), &delta); bump_day(KEY_UDAY_SLOT_PREFIX, &format!("{slot}:{day}"), &delta); } // =========================================================================== // 日桶(趋势图数据源) // =========================================================================== // // `ust:` / `utt:` 只留「今日 + 累计」两个数:今日跨天归零、累计不区分日期, // 都画不出历史曲线。所以另开一组**以自然日为键**的桶:一个桶一天, // 读取时按日窗 id **精确取键**(`get_live`),不做前缀扫描—— // 键数随时间增长也不会拖慢任何热路径。 /// 一天的聚合值 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] pub struct DayBucket { /// 请求数(已放行并真正转发) pub requests: i64, /// 入 token pub tin: i64, /// 出 token pub tout: i64, } impl DayBucket { fn merge(&mut self, other: &DayBucket) { self.requests += other.requests; self.tin += other.tin; self.tout += other.tout; } } /// `<请求数>:<入token>:<出token>` fn encode_day(b: &DayBucket) -> String { format!("{}:{}:{}", b.requests, b.tin, b.tout) } fn decode_day(payload: &str) -> DayBucket { let mut it = payload.split(':'); let num = |v: Option<&str>| v.and_then(|s| s.parse::().ok()).unwrap_or(0); DayBucket { requests: num(it.next()), tin: num(it.next()), tout: num(it.next()), } } /// 累加一日桶。TTL = `TREND_KEEP_SECS`,到期由共享内存自然淘汰 /// (`get_live` 视为不存在),不需要额外的清理任务。 fn bump_day(prefix: &[u8], name: &str, delta: &DayBucket) { // 用共享内存的 TTL 而不是读时比对——日桶是「写一次、读很多次」, // 让它自己过期比每次算保留窗口更省事,也避免键无限堆积。 let mut next = state::get_live(prefix, name.as_bytes(), util::now()) .map(|p| decode_day(&p)) .unwrap_or_default(); next.merge(delta); // 写入失败只记日志:统计是旁路功能,绝不影响转发 if !state::put( prefix, name.as_bytes(), encode_day(&next).as_bytes(), util::now() + TREND_KEEP_SECS, ) { util::log_err("[stats] 日桶写入失败(共享内存不足?)"); } } /// 读一个日桶(不存在 = 全 0) fn day_bucket(prefix: &[u8], name: &str) -> DayBucket { state::get_live(prefix, name.as_bytes(), util::now()) .map(|p| decode_day(&p)) .unwrap_or_default() } /// `<日窗id>:<入今日>:<入累计>:<出今日>:<出累计>:<最近时间戳>` fn encode_t(day: i64, t: &TokenUsage) -> String { format!( "{}:{}:{}:{}:{}:{}", day, t.tin_today, t.tin_total, t.tout_today, t.tout_total, t.last_ts ) } fn decode_t(payload: &str, day: i64) -> TokenUsage { let mut it = payload.split(':'); let stored_day = it.next().and_then(|s| s.parse::().ok()).unwrap_or(0); let in_today = it.next().and_then(|s| s.parse::().ok()).unwrap_or(0); let in_total = it.next().and_then(|s| s.parse::().ok()).unwrap_or(0); let out_today = it.next().and_then(|s| s.parse::().ok()).unwrap_or(0); let out_total = it.next().and_then(|s| s.parse::().ok()).unwrap_or(0); let last_ts = it.next().and_then(|s| s.parse::().ok()).unwrap_or(0); let live = stored_day == day; TokenUsage { tin_today: if live { in_today } else { 0 }, tin_total: in_total, tout_today: if live { out_today } else { 0 }, tout_total: out_total, last_ts, } } fn bump_t(prefix: &[u8], name: &str, tin: u64, tout: u64, day: i64, now: i64) { let current = state::get(prefix, name.as_bytes()) .map(|(payload, _)| decode_t(&payload, day)) .unwrap_or_default(); // 与 bump 同款读-增-写近似语义(并发下偶发少计),计量用途可接受 let next = TokenUsage { tin_today: current.tin_today + tin as i64, tin_total: current.tin_total + tin as i64, tout_today: current.tout_today + tout as i64, tout_total: current.tout_total + tout as i64, last_ts: now, }; state::put(prefix, name.as_bytes(), encode_t(day, &next).as_bytes(), 0); } /// 累加一次真实 token 消耗(来源:body filter 从上游响应抓到的 usage)。 /// 口径:只有抓到 usage 才记账;抓不到不补估。 pub fn add_tokens(username: &str, slot: &str, tin: u64, tout: u64, now: i64) { if username.is_empty() || slot.is_empty() || (tin == 0 && tout == 0) { return; } let day = util::day_id(now); bump_t(KEY_UTT_PREFIX, username, tin, tout, day, now); bump_t(KEY_UTMS_PREFIX, &format!("{username}:{slot}"), tin, tout, day, now); // 日桶:趋势图数据源(token 维度)。与 record 写的是同一批键,字段互补 let delta = DayBucket { tin: tin as i64, tout: tout as i64, ..Default::default() }; bump_day(KEY_UDAY_PREFIX, &day.to_string(), &delta); bump_day(KEY_UDAY_USER_PREFIX, &format!("{username}:{day}"), &delta); bump_day(KEY_UDAY_SLOT_PREFIX, &format!("{slot}:{day}"), &delta); } /// 删除账号时清理其全部用量键(`ust:` 与 `ums::*`)。 /// /// 用量键是**按前缀扫出来**做报表的(`all_users` / `all_models`),不清就会让 /// 已删除的账号继续挂在用量榜上。这与「删账号必须摘 `ukey:` 索引」是同类的 /// 正确性问题(只是影响面在报表而非鉴权,因此更容易被漏掉)。 pub fn forget(username: &str) { if username.is_empty() { return; } // 先物化键名再删,避免"遍历中改表"(四个键前缀同一套路) let prefix = format!("{username}:"); for p in [KEY_UST_PREFIX, KEY_UTT_PREFIX] { state::remove(p, username.as_bytes()); } // 日桶两个维度也要清:`udu::` 是按前缀扫不到的(键里还带日窗 id), // 靠 TTL 自然淘汰也能收敛,但删账号后趋势图仍会挂着幽灵账号 90 天 for p in [KEY_UMS_PREFIX, KEY_UTMS_PREFIX, KEY_UDAY_USER_PREFIX] { let keys: Vec = state::iter_prefix(p) .into_iter() .map(|(name, _)| name) .filter(|name| name.starts_with(&prefix)) .collect(); for name in keys { state::remove(p, name.as_bytes()); } } } // =========================================================================== // 读 // =========================================================================== /// 单账号读数(不含模型明细) pub fn user(username: &str, now: i64) -> Usage { let day = util::day_id(now); state::get(KEY_UST_PREFIX, username.as_bytes()) .map(|(payload, _)| decode(&payload, day)) .unwrap_or_default() } /// 单账号 × 上游明细,按 slot 升序 pub fn user_models(username: &str, now: i64) -> Vec<(String, Usage)> { let day = util::day_id(now); let prefix = format!("{username}:"); let mut out: Vec<(String, Usage)> = state::iter_prefix(KEY_UMS_PREFIX) .into_iter() .filter_map(|(name, payload)| { let slot = name.strip_prefix(&prefix)?.to_owned(); Some((slot, decode(&payload, day))) }) .collect(); out.sort_by(|a, b| a.0.cmp(&b.0)); out } /// 全部账号的用量(含各自的模型明细),按账号名升序。 /// /// 只扫一次 `ums:` 前缀再分组,避免"每个账号遍历一遍全表"。 pub fn all_users(now: i64) -> Vec { let day = util::day_id(now); let mut by_user: BTreeMap> = BTreeMap::new(); for (name, payload) in state::iter_prefix(KEY_UMS_PREFIX) { let Some((username, slot)) = name.split_once(':') else { continue; }; by_user .entry(username.to_owned()) .or_default() .push((slot.to_owned(), decode(&payload, day))); } for models in by_user.values_mut() { models.sort_by(|a, b| a.0.cmp(&b.0)); } state::iter_prefix(KEY_UST_PREFIX) .into_iter() .map(|(username, payload)| { let usage = decode(&payload, day); let models = by_user.remove(&username).unwrap_or_default(); UserUsage { username, usage, models } }) .collect() } /// 全部上游的用量(含用到它的账号明细),按 slot 升序。 pub fn all_models(now: i64) -> Vec { let day = util::day_id(now); // slot → (总量, 各账号) let mut by_slot: BTreeMap)> = BTreeMap::new(); for (name, payload) in state::iter_prefix(KEY_UMS_PREFIX) { let Some((username, slot)) = name.split_once(':') else { continue; }; let u = decode(&payload, day); let entry = by_slot.entry(slot.to_owned()).or_default(); entry.0.merge(&u); entry.1.push((username.to_owned(), u)); } by_slot .into_iter() .map(|(slot, (usage, mut users))| { users.sort_by(|a, b| a.0.cmp(&b.0)); ModelUsage { slot, usage, users } }) .collect() } /// 全局合计 pub fn totals(now: i64) -> Usage { let day = util::day_id(now); let mut sum = Usage::default(); for (_, payload) in state::iter_prefix(KEY_UST_PREFIX) { sum.merge(&decode(&payload, day)); } sum } /// 单账号 token 读数 pub fn tokens_user(username: &str, now: i64) -> TokenUsage { let day = util::day_id(now); state::get(KEY_UTT_PREFIX, username.as_bytes()) .map(|(payload, _)| decode_t(&payload, day)) .unwrap_or_default() } /// token 全表一次扫齐:`(按账号, 按上游, 按 账号→上游)`。 /// utt/utms 各扫一遍,避免报表页多次遍历共享内存。 fn tokens_scan( now: i64, ) -> ( BTreeMap, BTreeMap, BTreeMap>, ) { let day = util::day_id(now); let mut by_user: BTreeMap = BTreeMap::new(); for (name, payload) in state::iter_prefix(KEY_UTT_PREFIX) { by_user.insert(name, decode_t(&payload, day)); } let mut by_slot: BTreeMap = BTreeMap::new(); let mut by_pair: BTreeMap> = BTreeMap::new(); for (name, payload) in state::iter_prefix(KEY_UTMS_PREFIX) { let Some((username, slot)) = name.split_once(':') else { continue; }; let t = decode_t(&payload, day); by_slot.entry(slot.to_owned()).or_default().merge(&t); by_pair.entry(username.to_owned()).or_default().insert(slot.to_owned(), t); } (by_user, by_slot, by_pair) } /// 管理台用量页的完整投影 pub fn overview(now: i64) -> Value { let (t_by_user, t_by_slot, t_by_pair) = tokens_scan(now); let users: Vec = all_users(now) .into_iter() .map(|u| { let tin = t_by_pair.get(&u.username); json!({ "username": u.username, "today": u.usage.today, "total": u.usage.total, "last_ts": u.usage.last_ts, "last_ts_text": if u.usage.last_ts > 0 { util::fmt_time(u.usage.last_ts) } else { String::new() }, "tokens": t_by_user.get(&u.username).cloned().unwrap_or_default().json(), "models": u.models.iter().map(|(slot, usage)| { json!({ "slot": slot, "today": usage.today, "total": usage.total, "tokens": tin.and_then(|m| m.get(slot)).cloned().unwrap_or_default().json() }) }).collect::>(), }) }) .collect(); let models: Vec = all_models(now) .into_iter() .map(|m| { json!({ "slot": m.slot, "today": m.usage.today, "total": m.usage.total, "last_ts": m.usage.last_ts, "last_ts_text": if m.usage.last_ts > 0 { util::fmt_time(m.usage.last_ts) } else { String::new() }, "tokens": t_by_slot.get(&m.slot).cloned().unwrap_or_default().json(), "users": m.users.iter().map(|(name, usage)| { json!({ "username": name, "today": usage.today, "total": usage.total }) }).collect::>(), }) }) .collect(); let sum = totals(now); let mut tsum = TokenUsage::default(); for t in t_by_user.values() { tsum.merge(t); } json!({ "total": sum.json(), "tokens": tsum.json(), "users": users, "models": models, }) } // =========================================================================== // 趋势(图表数据源) // =========================================================================== /// 把一串日桶摊成图表直接能吃的三条等长数组 fn buckets_json(v: &[DayBucket]) -> Value { json!({ "requests": v.iter().map(|b| b.requests).collect::>(), "in": v.iter().map(|b| b.tin).collect::>(), "out": v.iter().map(|b| b.tout).collect::>(), }) } /// 最近 `days_req` 天的趋势序列(全局 / 按账号 / 按上游)。 /// /// `days_req` 会被夹到 `[1, TREND_DAYS_MAX]`——URL 里塞个 99999 也不会把 /// 共享内存扫爆。三个维度都是**按键精确取**(键名带日窗 id), /// 成本 = 天数 × (1 + 账号数 + 上游数) 次查表,且不随历史增长。 pub fn trend(now: i64, days_req: i64, users: &[String], slots: &[String]) -> Value { let days = days_req.clamp(1, TREND_DAYS_MAX); // 往前推 N 天:每个采样点一个时间戳,日窗 id 现算(本地自然日,不用 UTC) let stamps: Vec = (0..days).rev().map(|i| now - i * 86400).collect(); let labels: Vec = stamps.iter().map(|t| util::fmt_day(*t)).collect(); let ids: Vec = stamps.iter().map(|t| util::day_id(*t)).collect(); let total: Vec = ids.iter().map(|d| day_bucket(KEY_UDAY_PREFIX, &d.to_string())).collect(); let by_user: Vec = users .iter() .map(|u| { let series: Vec = ids .iter() .map(|d| day_bucket(KEY_UDAY_USER_PREFIX, &format!("{u}:{d}"))) .collect(); let mut o = buckets_json(&series); // 全 0 的账号不回传:趋势图里一堆积零的线只会把图例挤爆 let empty = series.iter().all(|b| b.requests == 0 && b.tin == 0 && b.tout == 0); if let Value::Object(ref mut m) = o { m.insert("username".to_owned(), json!(u)); m.insert("empty".to_owned(), json!(empty)); } o }) .collect(); let by_slot: Vec = slots .iter() .map(|s| { let series: Vec = ids .iter() .map(|d| day_bucket(KEY_UDAY_SLOT_PREFIX, &format!("{s}:{d}"))) .collect(); let empty = series.iter().all(|b| b.requests == 0 && b.tin == 0 && b.tout == 0); let mut o = buckets_json(&series); if let Value::Object(ref mut m) = o { m.insert("slot".to_owned(), json!(s)); m.insert("empty".to_owned(), json!(empty)); } o }) .collect(); json!({ "days": days, "labels": labels, "total": buckets_json(&total), "users": by_user, "slots": by_slot, }) } /// 趋势接口的默认天数(URL 没给 `days` 时用) pub fn trend_default_days() -> i64 { TREND_DAYS_DEFAULT }