Analytics & Usage Dashboards
Relevant source files
The following files were used as context for generating this wiki page:
The Analytics & Usage Dashboards provide a comprehensive interface for tracking LLM usage, costs, and session patterns across various profiles and providers within the CCS ecosystem. The system aggregates data from native runtimes (Claude, Codex) and proxy-based providers to surface insights into token consumption, cost analysis, and anomalous activity detection.
Sources: ui/src/pages/analytics/index.tsx:7-11, README.md:154-156
System Architecture & Data Flow
The analytics system follows a multi-tier architecture where a React-based frontend communicates with an Express web server. The server aggregates usage logs from various local directories (e.g., ~/.claude/projects, ~/.codex-native/sessions) and cached proxy data to provide a unified view.
The diagram shows the flow from the user interface down to the raw log files and usage caches.
Sources: ui/src/pages/analytics/hooks.ts:40-45, src/web-server/usage/handlers.ts:474-486, tests/unit/web-server/usage-aggregator-native-runtime-integration.test.ts:168-180
Analytics Frontend
Component Structure
The AnalyticsPage is structured as a grid containing a header for filtering, summary cards for high-level metrics, and a grid of charts for detailed trends.
| Component | Responsibility |
|---|---|
AnalyticsHeader | Manages date range selection, profile filtering, and manual refresh triggers. |
UsageSummaryCards | Displays total tokens, costs, and average usage per day. |
ChartsGrid | Renders daily/hourly trends, model breakdowns, and session lists. |
ModelDetailsContent | A popover content component showing specific metrics for a selected model. |
Sources: ui/src/pages/analytics/index.tsx:39-85
State Management & Hooks
The useAnalyticsPage hook centralizes state for the dashboard, including:
- Date Range: Defaults to the last 30 days.
- View Mode: Toggles between 'daily' and 'hourly' views.
- Profile Filtering: Supports "All profiles", "Default Claude", and specific account names.
- Model Selection: Manages the state for the model details popover.
Sources: ui/src/pages/analytics/hooks.ts:46-78
Backend Usage API
The backend provides several REST endpoints under /api/usage to serve the analytics frontend. It handles date validation (format YYYYMMDD), profile filtering, and pagination for session data.
API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/usage/summary | GET | Returns aggregated totals for tokens and costs within a date range. |
/usage/daily | GET | Provides daily usage trends. |
/usage/hourly | GET | Provides hourly usage trends with gap filling for inactive periods. |
/usage/models | GET | Breaks down usage by specific model and provider. |
/usage/sessions | GET | Returns paginated session history with project paths and token counts. |
/usage/insights | GET | Returns detected anomalies (e.g., cost spikes, high I/O ratios). |
/usage/refresh | POST | Clears server-side usage cache and triggers a fresh aggregation. |
Sources: src/web-server/usage/handlers.ts:474-672, ui/src/hooks/use-usage.ts:133-176
Data Models
The system tracks usage across several token categories to calculate precise costs based on model-specific pricing.
Sources: ui/src/hooks/use-usage.ts:9-35
Anomaly Detection Logic
The system includes an automated anomaly detection engine that monitors usage for patterns that might indicate excessive spending or technical issues.
| Anomaly Type | Threshold | Description |
|---|---|---|
cost_spike | 2x Avg Daily Cost | Triggered when a day's cost exceeds the average by a specific multiplier. |
high_input | 10M Tokens | Triggered when a single request's input tokens exceed the 10 million limit. |
high_io_ratio | 100:1 | Triggered when the ratio of input tokens to output tokens is excessively high. |
high_cache_read | 1B Tokens | Triggered by unusually high cache read token volume. |
Sources: src/web-server/usage/handlers.ts:54-59, src/web-server/usage/handlers.ts:392-436
Implementation Details
API Query Serialization
The frontend serializes date ranges into since and until parameters using the YYYYMMDD format. This ensures compatibility with the backend's validation logic.
// ui/src/hooks/use-usage.ts:114-119
function formatDateForApi(date: Date): string {
const year = date.getFullYear();
const month = String(date.getMonth() + 1).padStart(2, '0');
const day = String(date.getDate()).padStart(2, '0');
return `${year}${month}${day}`;
}
Sources: ui/src/hooks/use-usage.ts:114-119, ui/tests/unit/ui/pages/analytics/usage-api-contract.test.ts:24-34
Native Runtime Integration
The aggregator is designed to prevent double-counting. For instance, when aggregating Codex logs, it specifically ignores rollouts that are already being tracked via proxy bridges.
Summary
The Analytics & Usage Dashboards serve as the central observability hub for the CCS project. By unifying logs from native tools (Claude/Codex) and proxy-routed requests, it provides developers with a clear understanding of their AI consumption and costs. The integration of anomaly detection further adds a layer of safety by alerting users to unexpected usage patterns.