pub struct CostTracker { /* private fields */ }Expand description
Accumulates token usage and USD spend, optionally against a budget.
- Totals are stored in fixed point (units of $0.0001) in atomics, so
CostTracker::total_usd,CostTracker::total_input_tokensandCostTracker::total_output_tokensare lock-free andSend + Sync. - The per-model breakdown is guarded by a
std::sync::Mutex. - Cloning a tracker shares the same underlying state (all fields are
Arc-backed), so all clones observe the same spend.
§Budget semantics
CostTracker::record checks the budget before mutating any state. A
record that would push total spend past the limit is rejected with
RouterError::BudgetExceeded and nothing is accumulated. Therefore, as
long as every call is gated through record, tracked spend can never
exceed the limit.
§Example
use model_router::{CostTracker, ModelPricing};
let tracker = CostTracker::new(Some(0.01)); // $0.01 budget
let pricing = ModelPricing::new(3.0, 15.0); // Claude Sonnet class
tracker.record("claude-sonnet-4", 100, 50, &pricing).unwrap();
assert!(tracker.total_usd() < 0.01);
assert!(!tracker.is_over_budget());Implementations§
Source§impl CostTracker
impl CostTracker
Sourcepub fn new(budget_limit_usd: Option<f64>) -> Self
pub fn new(budget_limit_usd: Option<f64>) -> Self
Create a new cost tracker, optionally with a USD budget limit.
Sourcepub fn budget_limit_usd(&self) -> Option<f64>
pub fn budget_limit_usd(&self) -> Option<f64>
The configured budget limit in USD, if any.
Sourcepub fn record(
&self,
model: &str,
input_tokens: usize,
output_tokens: usize,
pricing: &ModelPricing,
) -> Result<(), RouterError>
pub fn record( &self, model: &str, input_tokens: usize, output_tokens: usize, pricing: &ModelPricing, ) -> Result<(), RouterError>
Record token usage for model, priced with pricing.
Fails with RouterError::BudgetExceeded (without mutating any
state) if the record would push total spend past the budget limit.
§Precision
Costs are accumulated in fixed point at $0.0001 granularity and
truncated into that grid, so a recorded delta never exceeds the
true cost and tracked totals err slightly low. Costs under $0.0001
(a hundredth of a cent) truncate to zero. The budget pre-check itself
runs in f64, so enforcement precision is unaffected.
Sourcepub fn total_input_tokens(&self) -> u64
pub fn total_input_tokens(&self) -> u64
Total input tokens recorded across all models.
Sourcepub fn total_output_tokens(&self) -> u64
pub fn total_output_tokens(&self) -> u64
Total output tokens recorded across all models.
Sourcepub fn remaining_usd(&self) -> Option<f64>
pub fn remaining_usd(&self) -> Option<f64>
Unspent budget in USD (None when no budget is configured). Never
negative; zero once the budget is exhausted.
Sourcepub fn per_model_breakdown(&self) -> BTreeMap<String, ModelCostBreakdown>
pub fn per_model_breakdown(&self) -> BTreeMap<String, ModelCostBreakdown>
Per-model cost breakdown.
Sourcepub fn is_over_budget(&self) -> bool
pub fn is_over_budget(&self) -> bool
Whether total spend has reached or exceeded the budget limit.
Always false when no budget is configured.
Sourcepub fn report(&self) -> CostReport
pub fn report(&self) -> CostReport
Build a CostReport snapshot of the current state.