agent-orchestrator/docs/pro/features/analytics.md

Analytics Dashboard

This documentation covers Pro edition features available in the agents-orchestrator/agents-orchestrator private repository.

Overview

The Analytics Dashboard provides historical cost and usage visibility across all projects. It reads from the community session_metrics table (no additional data collection required) and presents aggregated views through three commands and corresponding UI components.

Data Source

All analytics are derived from the existing session_metrics table in sessions.db:

-- Community table (read-only access from Pro plugin)
CREATE TABLE session_metrics (
    id INTEGER PRIMARY KEY,
    project_id TEXT NOT NULL,
    session_id TEXT NOT NULL,
    started_at TEXT,
    ended_at TEXT,
    peak_tokens INTEGER,
    turn_count INTEGER,
    tool_call_count INTEGER,
    cost_usd REAL,
    model TEXT,
    status TEXT,
    error_message TEXT
);

The Pro plugin opens a read-only connection to sessions.db and queries this table. It never writes to community databases.

Commands

pro_analytics_summary

Returns an aggregated summary for the specified period.

Arguments:

Field	Type	Required	Description
period	u32	Yes	Number of days to look back (7, 14, 30, or 90)
projectId	String	No	Filter to a single project. Omit for all projects.

Response: AnalyticsSummary

interface AnalyticsSummary {
  totalCostUsd: number;
  totalSessions: number;
  totalTurns: number;
  totalToolCalls: number;
  avgCostPerSession: number;
  avgTurnsPerSession: number;
  peakTokensMax: number;
  periodDays: number;
  projectCount: number;
}

pro_analytics_daily

Returns per-day statistics for charting.

Arguments:

Field	Type	Required	Description
period	u32	Yes	Number of days (7, 14, 30, or 90)
projectId	String	No	Filter to a single project

Response: Vec<DailyStats>

interface DailyStats {
  date: string;          // ISO 8601 date (YYYY-MM-DD)
  costUsd: number;
  sessionCount: number;
  turnCount: number;
  toolCallCount: number;
}

Days with no sessions are included with zero values to ensure continuous chart data.

pro_analytics_model_breakdown

Returns usage grouped by model.

Arguments:

Field	Type	Required	Description
period	u32	Yes	Number of days (7, 14, 30, or 90)
projectId	String	No	Filter to a single project

Response: Vec<ModelBreakdown>

interface ModelBreakdown {
  model: string;
  sessionCount: number;
  totalCostUsd: number;
  avgCostPerSession: number;
  totalTurns: number;
  totalToolCalls: number;
  pctOfTotalCost: number;  // 0.0 to 100.0
}

Results are sorted by totalCostUsd descending.

Period Selection

The UI presents four period options:

Period	Label	Use Case
7	Last 7 days	Recent activity check
14	Last 14 days	Sprint review
30	Last 30 days	Monthly cost review
90	Last 90 days	Quarterly trend analysis

The selected period is stored in the component state and defaults to 30 days. Changing the period triggers a fresh query (no client-side caching).

UI Components

AnalyticsDashboard.svelte

Top-level Pro tab component. Contains:

1. Period selector -- segmented button group (7/14/30/90).
2. Summary cards -- four stat cards showing total cost, sessions, avg cost/session, peak tokens.
3. Daily cost chart -- SVG bar chart rendered from DailyStats[].
4. Model breakdown table -- sortable table from ModelBreakdown[].

Daily Cost Chart

The chart is a pure SVG element (no charting library). Implementation details:

• Bars are sized relative to the maximum daily cost in the period.
• X-axis labels show abbreviated dates (e.g., "Mar 5").
• Y-axis shows cost in USD with appropriate precision ($0.01 for small values, $1.00 for large).
• Hover tooltip shows exact cost, session count, and turn count for the day.
• Colors use var(--ctp-blue) for bars, var(--ctp-surface1) for gridlines.
• Responsive: adapts bar width to container via container-type: inline-size.

Model Breakdown Table

Standard sortable table with columns: Model, Sessions, Cost, Avg Cost, Turns, Tools, % of Total. Default sort by cost descending. The % of Total column includes a proportional bar using var(--ctp-sapphire).

IPC Examples

// Get 30-day summary across all projects
const summary = await invoke('plugin:agor-pro|pro_analytics_summary', {
  period: 30,
});

// Get daily stats for a specific project
const daily = await invoke('plugin:agor-pro|pro_analytics_daily', {
  period: 14,
  projectId: 'my-project',
});

// Get model breakdown
const models = await invoke('plugin:agor-pro|pro_analytics_model_breakdown', {
  period: 90,
});

Limitations

• Analytics are computed on-demand from raw session_metrics rows. For large datasets (10,000+ sessions), queries may take 100-200ms. No materialized views or pre-aggregation.
• Historical data depends on community session_metrics persistence. If sessions.db is deleted or migrated, analytics history resets.
• Cost values are only available for providers that report cost (Claude, Codex). Ollama sessions show $0.00.