Usage Analytics Dashboard
Relevant source files
The following files were used as context for generating this wiki page:
The Usage Analytics Dashboard is a comprehensive monitoring interface designed to track Claude API consumption, associated costs, and session performance within the opcode application. It provides developers and administrators with granular insights into how LLM resources are utilized across different projects and models.
The system aggregates data from various telemetry points and API response metadata, offering a multi-dimensional view through interactive charts, breakdown tables, and summary cards. It serves as a centralized hub for financial oversight and technical performance auditing of AI-assisted development tasks.
Sources: README.md:120-125, src/components/UsageDashboard.tsx:28-33
System Architecture and Data Flow
The dashboard operates on a decoupled architecture where the frontend React component interacts with the Rust backend via a TypeScript API client. Data is retrieved asynchronously, processed for visualization, and stored in a local cache to minimize redundant network requests.
Data Acquisition Flow
The following sequence diagram illustrates how the dashboard fetches and renders usage statistics:
The dashboard uses a 10-minute cache duration (CACHE_DURATION) to optimize performance and supports progressive loading for its sub-tabs.
Sources: src/components/UsageDashboard.tsx:23-24, src/components/UsageDashboard.tsx:88-120, src/lib/api.ts:223-255
Key Data Models
The analytics system is built around several core data structures that represent different facets of API consumption.
Usage Statistics Summary
The UsageStats interface represents the aggregate data for a selected period.
| Field | Type | Description |
|---|---|---|
total_cost | number | Total USD spent across all sessions. |
total_tokens | number | Aggregate count of all tokens processed. |
total_input_tokens | number | Total tokens sent in prompts. |
total_output_tokens | number | Total tokens generated by Claude. |
total_sessions | number | Count of unique Claude Code sessions. |
by_model | ModelUsage[] | Token and cost breakdown per model. |
by_project | ProjectUsage[] | Usage statistics categorized by project path. |
Sources: src/lib/api.ts:182-192, src/components/UsageDashboard.tsx:165-188
Token Breakdown Details
The system specifically tracks advanced token categories to provide an accurate reflection of Claude's caching mechanisms:
- Cache Write Tokens: Tokens used to create new cache entries.
- Cache Read Tokens: Tokens retrieved from existing cache entries, typically at a lower cost.
Sources: src/lib/api.ts:168-171, src/components/UsageDashboard.tsx:244-255
Core Features and View Modes
The dashboard is organized into five primary tabs, each utilizing memoized components for efficient rendering.
1. Overview Tab
Provides a high-level summary including "Summary Cards" for cost, sessions, and tokens, alongside quick-access lists for "Most Used Models" and "Top Projects."
Sources: src/components/UsageDashboard.tsx:238-278
2. Model Analytics
Displays a detailed matrix of consumption per model (e.g., Claude 4 Opus, Sonnet 3.5).
3. Project and Session Tracking
The "By Project" and "By Session" views provide paginated lists of usage. This allows users to identify high-cost projects or specific long-running sessions. The "By Session" view includes metadata such as the project path, last used date, and session-specific costs.
Sources: src/components/UsageDashboard.tsx:327-415
4. Timeline Visualization
Features a daily usage chart that renders cost trends over time. It calculates the maxCost and halfMaxCost for dynamic Y-axis scaling and uses a bar chart representation where each bar includes a detailed tooltip on hover.
Sources: src/components/UsageDashboard.tsx:195-212, src/components/UsageDashboard.tsx:419-470
Telemetry and Event Tracking
The Usage Dashboard is complemented by a robust analytics tracking system that logs user interactions to help improve the application.
Event Classification
Events are categorized into specific types to ensure consistent structure across the telemetry pipeline.
| Event Category | Key Events | File Reference |
|---|---|---|
| Session | PROMPT_SUBMITTED, SESSION_STOPPED, CHECKPOINT_RESTORED | events.ts:31-38 |
| Feature Adoption | FEATURE_DISCOVERED, FEATURE_ADOPTED | events.ts:88-89 |
| Performance | PERFORMANCE_BOTTLENECK, MEMORY_WARNING, RESOURCE_USAGE_HIGH | events.ts:74-75 |
| Agent | AGENT_STARTED, AGENT_PROGRESS, AGENT_ERROR | events.ts:49-52 |
Event Implementation Example
The useAnalytics hook provides a standardized interface for triggering these events from UI components.
// Example from src/hooks/useAnalytics.ts
export function useTrackEvent() {
return {
// Tracks when the user selects a different model in the dashboard or chat
modelSelected: (newModel: string, previousModel?: string, source?: string) => {
const event = eventBuilders.model(newModel, previousModel, source);
analytics.track(event.event, event.properties);
},
// Tracks aggregate session metrics upon completion
enhancedSessionStopped: (props: EnhancedSessionStoppedProperties) => {
const event = eventBuilders.enhancedSessionStopped(props);
analytics.track(event.event, event.properties);
}
};
}
Sources: src/hooks/useAnalytics.ts:74-78, src/hooks/useAnalytics.ts:139-142
Data Formatting and I18n
The dashboard utilizes the Intl API for localized formatting and the i18next framework for multi-language support.
- Currency Formatting: Costs are formatted as USD with a minimum and maximum of 2 fraction digits.
- Token Abbreviation: Large token counts are abbreviated for readability (e.g.,
1,000,000becomes1.00M,1,000becomes1.0K). - Localization: All labels (e.g.,
usage.totalCost,usage.cacheRead) are retrieved from the English locale file (en.json).
Sources: src/components/UsageDashboard.tsx:50-70, src/i18n/locales/en.json:440-475
Summary
The Usage Analytics Dashboard integrates high-level summary metrics with granular project and session data to provide a transparent view of LLM operations. By leveraging a memoized React architecture and parallel backend API calls, it maintains high performance even when processing large volumes of historical usage data. Through its comprehensive event tracking and detailed token breakdown, it offers the necessary tools for both financial management and technical optimization of the Claude Code environment.