//! 通用记账原语(无任何业务语义)。 //! //! 只回答「给这个前缀下的这个键 +1」「这个键现在的读数是什么」—— //! **不认识** `ust:` 与 `ums:` 的区别,更不认识「LLM」「token」这些词。 //! 业务解读(趋势 / 总览 / 按人聚合)在 plugin-llm 的 `stats` 模块, //! 它把键前缀与本模块的原语组合起来。 //! //! value 编码共用两种: //! * 窗口读数:`<日窗id>:<今日数>:<累计数>:<最近调用时间戳>` //! * 日桶:`<请求数>:<入>:<出>`(趋势图数据源,TTL 到期自然淘汰) use serde_json::{Value, json}; 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` 取最大。 pub 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 pub tin_today: i64, /// 累计入 token pub tin_total: i64, /// 今日出 token pub tout_today: i64, /// 累计出 token pub tout_total: i64, /// 最近一次有 token 记账的调用时间戳;0 = 从未 pub last_ts: i64, } impl TokenUsage { /// 累加(聚合用)。`last_ts` 取最大。 pub 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() }, }) } } /// 一天的聚合值(日桶) #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] pub struct DayBucket { pub requests: i64, pub tin: i64, pub tout: i64, } impl DayBucket { pub fn merge(&mut self, other: &DayBucket) { self.requests += other.requests; self.tin += other.tin; self.tout += other.tout; } } // =========================================================================== // 窗口读数(<日窗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 } } /// 窗口计数 +1(读-增-写不加写锁的近似语义:并发下偶发少计一次, /// 统计用途无影响;换来的是调用方热路径不为统计抢锁)。 pub 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, }; state::put(prefix, name.as_bytes(), encode(day, &next).as_bytes(), 0); } /// 读窗口读数(不跨窗折算由 decode 按 day 完成) pub fn read(prefix: &[u8], name: &str, day: i64) -> Usage { state::get(prefix, name.as_bytes()) .map(|(payload, _)| decode(&payload, day)) .unwrap_or_default() } // =========================================================================== // token 窗口读数(<日窗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, } } /// token 窗口累加(同 bump 的近似语义) pub 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(); 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 窗口读数 pub fn read_t(prefix: &[u8], name: &str, day: i64) -> TokenUsage { state::get(prefix, name.as_bytes()) .map(|(payload, _)| decode_t(&payload, day)) .unwrap_or_default() } // =========================================================================== // 日桶(趋势图数据源) // =========================================================================== // // 以自然日为键的桶:一个桶一天,读取时按日窗 id **精确取键**(get_live), // 不做前缀扫描——键数随时间增长也不会拖慢任何热路径。 // TTL 由调用方传入(业务保留策略属于插件,不属于本模块)。 /// `<请求数>:<入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_secs` 为保留时长(到期由共享内存自然淘汰)。 pub fn bump_day(prefix: &[u8], name: &str, delta: &DayBucket, ttl_secs: i64) { 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() + ttl_secs, ) { util::log_err("[usage] 日桶写入失败(共享内存不足?)"); } } /// 读一个日桶(不存在 = 全 0) pub 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() }