Module aggregation 

Aggregation module for summarizing usage data

This module provides functionality to aggregate raw usage entries into meaningful summaries like daily usage, monthly rollups, session statistics, and billing blocks.

Cloning Strategy

This module follows a deliberate cloning strategy to balance performance and simplicity:

• Entry References: Methods take &UsageEntry to avoid unnecessary moves of large structs.
• Model Names: We clone ModelName strings when inserting into HashSets/Maps because:
  • Model names are typically small strings (e.g., “claude-3-opus”)
  • There are only a few dozen unique model names at most
  • The alternative (Arc or string interning) adds complexity for minimal benefit
• Stream Processing: When processing streams, we clone entries individually rather than cloning entire collections, which reduces peak memory usage for large datasets.

Future optimization opportunities (if profiling shows bottlenecks):

• Use the existing string interning infrastructure in string_pool.rs for model names
• Switch to Arc<ModelName> for shared ownership without cloning
• Implement zero-copy aggregation using lifetimes (complex but most efficient)

Examples

use ccstat::{
    aggregation::Aggregator,
    cost_calculator::CostCalculator,
    data_loader::DataLoader,
    pricing_fetcher::PricingFetcher,
    timezone::TimezoneConfig,
    types::CostMode,
};
use std::sync::Arc;

let pricing_fetcher = Arc::new(PricingFetcher::new(false).await);
let cost_calculator = Arc::new(CostCalculator::new(pricing_fetcher));
let aggregator = Aggregator::new(cost_calculator, TimezoneConfig::default());

let data_loader = DataLoader::new().await?;
let entries = data_loader.load_usage_entries_parallel();

// Aggregate by day
let daily_data = aggregator.aggregate_daily(entries, CostMode::Auto).await?;

// Create monthly rollups
let monthly_data = Aggregator::aggregate_monthly(&daily_data);

Structs

Aggregator

Main aggregation engine

BillingBlockParams

Parameters for creating and filtering billing blocks

DailyInstanceUsage

Daily usage grouped by instance

DailyUsage

Daily usage summary

MonthlyUsage

Monthly usage summary

SessionBlock

5-hour billing block

SessionUsage

Session usage summary

Totals

Calculate totals from aggregated data

VerboseEntry

Verbose entry for detailed token information

Functions

apply_token_limit_warnings

Helper function to apply token limit warnings to blocks Returns Result to handle parsing errors

create_and_filter_billing_blocks

Shared function to create and filter billing blocks from usage entries.

filter_blocks

Helper function to filter blocks based on active and recent flags

filter_blocks_by_date

Helper function to filter blocks based on date range

filter_blocks_by_project

Helper function to filter blocks based on project

filter_monthly_data

Helper function to filter monthly data based on a MonthFilter