analytics

package
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 26, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ClassifyTask 

func ClassifyTask(prompt string, response string) string

ClassifyTask determines the task type from a prompt/response pair. Returns one of: "simple", "generation", "debug", "refactor", "review", "chat".

func DetectMidTaskCompaction 

func DetectMidTaskCompaction(toolsBefore, toolsAfter []string) bool

DetectMidTaskCompaction returns true if any tool name appears in both windows, indicating compaction interrupted active work.

func ExportInsightsHTML 

func ExportInsightsHTML(report *InsightsReport) string

ExportInsightsHTML generates an HTML report from insights.

func FormatOptimizationReport 

func FormatOptimizationReport(r *OptimizationReport) string

FormatOptimizationReport produces a human-readable optimization report.

func FormatStats 

func FormatStats(s *SessionStats) string

FormatStats produces a human-readable stats report.

func LogEvent 

func LogEvent(name, sessionID string, properties map[string]interface{})

LogEvent logs an analytics event.

func SaveInsightsReport 

func SaveInsightsReport(report *InsightsReport) (string, error)

SaveInsightsReport saves an HTML report to disk.

func SaveTrace 

func SaveTrace(t *SessionTrace) error

SaveTrace saves a session trace.

func SuggestModel 

func SuggestModel(taskType string, currentModel string) string

SuggestModel recommends the cheapest adequate model for a task type. If currentModel is empty, it returns the recommended model for the task type.

func Summary 

func Summary() string

Summary returns a formatted analytics summary.

Types

type ActivityTracker 

type ActivityTracker struct {
	// contains filtered or unexported fields
}

ActivityTracker tracks user typing vs CLI/agent execution time to provide a ratio of how much time the user spends vs how much the agent works.

func NewActivityTracker 

func NewActivityTracker() *ActivityTracker

NewActivityTracker creates a new ActivityTracker.

func (*ActivityTracker) EndExecution 

func (a *ActivityTracker) EndExecution()

EndExecution marks the end of an agent/tool execution period.

func (*ActivityTracker) EndUserInput 

func (a *ActivityTracker) EndUserInput()

EndUserInput marks the end of user input time.

func (*ActivityTracker) ExecTime 

func (a *ActivityTracker) ExecTime() time.Duration

ExecTime returns the accumulated execution duration.

func (*ActivityTracker) StartExecution 

func (a *ActivityTracker) StartExecution()

StartExecution marks the beginning of an agent/tool execution period.

func (*ActivityTracker) StartUserInput 

func (a *ActivityTracker) StartUserInput()

StartUserInput marks the beginning of user input time.

func (*ActivityTracker) Summary 

func (a *ActivityTracker) Summary() string

Summary returns a formatted summary: "User: 5m30s | Agent: 12m15s | Ratio: 2.2x"

func (*ActivityTracker) UserTime 

func (a *ActivityTracker) UserTime() time.Duration

UserTime returns the accumulated user input duration.

type BudgetViolation 

type BudgetViolation struct {
	SLO       string
	Expected  float64
	Actual    float64
	Timestamp time.Time
	Duration  time.Duration
}

BudgetViolation records when an SLO was violated.

type CommandContext 

type CommandContext struct {
	Command  string        `json:"command"`
	ExitCode int           `json:"exit_code"`
	Duration time.Duration `json:"duration"`
	CWD      string        `json:"cwd"`
}

CommandContext captures metadata about a shell command execution.

type CommandTracker 

type CommandTracker struct {
	// contains filtered or unexported fields
}

CommandTracker records shell command executions for analytics.

func (*CommandTracker) AvgDuration 

func (t *CommandTracker) AvgDuration() time.Duration

AvgDuration returns the average duration across all recorded commands.

func (*CommandTracker) FailureRate 

func (t *CommandTracker) FailureRate() float64

FailureRate returns the fraction of commands with non-zero exit codes.

func (*CommandTracker) MostUsed 

func (t *CommandTracker) MostUsed(n int) []string

MostUsed returns the top n most frequently used commands.

func (*CommandTracker) Record 

func (t *CommandTracker) Record(cmd string, exitCode int, duration time.Duration, cwd string)

Record adds a command execution to the tracker.

type CostEntry 

type CostEntry struct {
	SessionID    string        `json:"session_id"`
	Model        string        `json:"model"`
	TaskType     string        `json:"task_type"` // "simple", "generation", "debug", "refactor", "review", "chat"
	InputTokens  int           `json:"input_tokens"`
	OutputTokens int           `json:"output_tokens"`
	CostUSD      float64       `json:"cost_usd"`
	Duration     time.Duration `json:"duration"`
	Kept         bool          `json:"kept"` // was the output used/kept?
	Timestamp    time.Time     `json:"timestamp"`
}

CostEntry represents a single LLM API call with cost metadata.

type DashModelStats 

type DashModelStats struct {
	Requests     int     `json:"requests"`
	Tokens       int     `json:"tokens"`
	CostUSD      float64 `json:"cost_usd"`
	AvgLatencyMs int     `json:"avg_latency_ms"`
	ErrorRate    float64 `json:"error_rate"`
}

DashModelStats tracks usage and performance per model for the dashboard.

type Dashboard 

type Dashboard struct {
	Sessions     []SessionSummary          `json:"sessions"`
	DailyStats   []DayStat                 `json:"daily_stats"`
	ModelUsage   map[string]DashModelStats `json:"model_usage"`
	ToolUsage    map[string]int            `json:"tool_usage"`
	TotalCostUSD float64                   `json:"total_cost_usd"`
	TotalTokens  int                       `json:"total_tokens"`
	ActiveDays   int                       `json:"active_days"`
}

Dashboard provides a local telemetry dashboard for hawk showing usage analytics, performance metrics, and session history in a terminal-friendly format.

func NewDashboard 

func NewDashboard() *Dashboard

NewDashboard creates an initialized empty Dashboard.

func (*Dashboard) Export 

func (d *Dashboard) Export() ([]byte, error)

Export serializes the dashboard data to JSON.

func (*Dashboard) Import 

func (d *Dashboard) Import(data []byte) error

Import deserializes JSON data into the dashboard.

func (*Dashboard) RecordSession 

func (d *Dashboard) RecordSession(summary SessionSummary)

RecordSession adds a session summary to the dashboard and updates aggregates.

func (*Dashboard) RenderCostChart 

func (d *Dashboard) RenderCostChart(days int) string

RenderCostChart renders an ASCII bar chart of daily costs for the given number of days.

func (*Dashboard) RenderModelBreakdown 

func (d *Dashboard) RenderModelBreakdown() string

RenderModelBreakdown renders a pie-chart-like breakdown with percentages for each model.

func (*Dashboard) RenderOverview 

func (d *Dashboard) RenderOverview() string

RenderOverview produces a terminal-friendly overview of usage analytics.

func (*Dashboard) RenderRecentSessions 

func (d *Dashboard) RenderRecentSessions(n int) string

RenderRecentSessions renders a table of the last n sessions.

func (*Dashboard) RenderTokenChart 

func (d *Dashboard) RenderTokenChart(days int) string

RenderTokenChart renders an ASCII bar chart of daily token usage for the given number of days.

type DateRange 

type DateRange struct {
	Start time.Time `json:"start"`
	End   time.Time `json:"end"`
}

DateRange represents the time span of statistics.

type DayStat 

type DayStat struct {
	Date        time.Time     `json:"date"`
	Sessions    int           `json:"sessions"`
	Tokens      int           `json:"tokens"`
	CostUSD     float64       `json:"cost_usd"`
	AvgDuration time.Duration `json:"avg_duration"`
}

DayStat aggregates metrics for a single day.

type Event 

type Event struct {
	Name       string                 `json:"name"`
	Timestamp  time.Time              `json:"timestamp"`
	SessionID  string                 `json:"session_id,omitempty"`
	Properties map[string]interface{} `json:"properties,omitempty"`
}

Event represents an analytics event.

type InsightsFacet 

type InsightsFacet struct {
	Category string   `json:"category"` // goals, outcomes, friction, success
	Items    []string `json:"items"`
}

InsightsFacet represents an extracted insight category.

type InsightsReport 

type InsightsReport struct {
	GeneratedAt     time.Time       `json:"generated_at"`
	SessionsScanned int             `json:"sessions_scanned"`
	DateRange       DateRange       `json:"date_range"`
	Facets          []InsightsFacet `json:"facets"`
	TopPatterns     []string        `json:"top_patterns"`
	Recommendations []string        `json:"recommendations"`
	Stats           *SessionStats   `json:"stats,omitempty"`
}

InsightsReport holds a complete cross-session analysis.

func GenerateInsights 

func GenerateInsights(days int, analysisFn func(content string) ([]InsightsFacet, error)) (*InsightsReport, error)

GenerateInsights analyzes session transcripts to extract patterns and recommendations.

type ModelSpend 

type ModelSpend struct {
	Model     string  `json:"model"`
	TotalCost float64 `json:"total_cost"`
	Calls     int     `json:"calls"`
	AvgTokens int     `json:"avg_tokens"`
}

ModelSpend aggregates cost data for a specific model.

type ModelStats 

type ModelStats struct {
	Model      string  `json:"model"`
	Tokens     int64   `json:"tokens"`
	Requests   int     `json:"requests"`
	AvgLatency float64 `json:"avg_latency_ms"`
	Cost       float64 `json:"cost"`
}

ModelStats tracks usage per model.

type OneShotTracker 

type OneShotTracker struct {
	// contains filtered or unexported fields
}

OneShotTracker tracks the percentage of edit turns that succeed without retries.

func (*OneShotTracker) Rate 

func (t *OneShotTracker) Rate() float64

Rate returns the one-shot success rate as a percentage (0-100).

func (*OneShotTracker) RecordTurn 

func (t *OneShotTracker) RecordTurn(toolNames []string)

RecordTurn records a turn's tool usage for one-shot rate calculation. An edit turn immediately followed by another edit turn = retry.

func (*OneShotTracker) Stats 

func (t *OneShotTracker) Stats() (total, firstTry int)

Stats returns total edits and first-try successes.

type OptimizationReport 

type OptimizationReport struct {
	TotalSpend      float64                `json:"total_spend"`
	WastedSpend     float64                `json:"wasted_spend"`     // spend on simple tasks with expensive models
	AbandonedSpend  float64                `json:"abandoned_spend"`  // spend on outputs that were discarded
	ProductiveSpend float64                `json:"productive_spend"` // spend on outputs that were kept
	YieldRate       float64                `json:"yield_rate"`       // productive / total
	Recommendations []Recommendation       `json:"recommendations"`
	ByModel         map[string]*ModelSpend `json:"by_model"`
	ByTaskType      map[string]*TaskSpend  `json:"by_task_type"`
}

OptimizationReport contains spend analysis and recommendations.

func Analyze 

func Analyze(entries []CostEntry) *OptimizationReport

Analyze examines cost entries and produces optimization recommendations.

type PerfBudget 

type PerfBudget struct {
	SLOs       map[string]*SLO
	Violations []BudgetViolation
	// contains filtered or unexported fields
}

PerfBudget tracks agent performance against defined SLOs.

func NewPerfBudget 

func NewPerfBudget() *PerfBudget

NewPerfBudget creates a PerfBudget with default SLOs.

func (*PerfBudget) AddSLO 

func (pb *PerfBudget) AddSLO(slo SLO)

AddSLO adds or updates an SLO.

func (*PerfBudget) Check 

func (pb *PerfBudget) Check() map[string]string

Check evaluates all SLOs and returns status per SLO.

func (*PerfBudget) FormatDashboard 

func (pb *PerfBudget) FormatDashboard() string

FormatDashboard returns a formatted string representing the performance budget dashboard.

func (*PerfBudget) GetViolations 

func (pb *PerfBudget) GetViolations(since time.Time) []BudgetViolation

GetViolations returns violations that occurred since the given time.

func (*PerfBudget) ProjectTrend 

func (pb *PerfBudget) ProjectTrend(metric string) string

ProjectTrend analyzes measurements for a metric and returns the trend direction.

func (*PerfBudget) Record 

func (pb *PerfBudget) Record(metric string, value float64)

Record adds a measurement for the given metric.

func (*PerfBudget) Reset 

func (pb *PerfBudget) Reset()

Reset clears all measurements and violations.

type Recommendation 

type Recommendation struct {
	Type        string  `json:"type"` // "downgrade", "batch", "cache"
	Description string  `json:"description"`
	Savings     float64 `json:"savings"` // estimated USD savings
}

Recommendation represents a cost optimization suggestion.

type SLO 

type SLO struct {
	Name         string
	Metric       string
	Target       float64
	Window       time.Duration
	Current      float64
	Measurements []float64
	Status       string // "met", "at_risk", "violated"
}

SLO defines a Service Level Objective for a performance metric.

type SessionAnalytics 

type SessionAnalytics struct {
	Sessions []SessionData
	// contains filtered or unexported fields
}

SessionAnalytics tracks and reports on agent behavior patterns over time.

func NewSessionAnalytics 

func NewSessionAnalytics() *SessionAnalytics

NewSessionAnalytics creates a new SessionAnalytics instance.

func (*SessionAnalytics) CostProjection 

func (sa *SessionAnalytics) CostProjection(daysAhead int) float64

CostProjection estimates cost for the given number of days ahead based on historical average daily spending.

func (*SessionAnalytics) DailyReport 

func (sa *SessionAnalytics) DailyReport(date time.Time) string

DailyReport generates a formatted report for the given date.

func (*SessionAnalytics) Export 

func (sa *SessionAnalytics) Export(format string) string

Export exports session data in the specified format ("csv" or "json").

func (*SessionAnalytics) FormatOverview 

func (sa *SessionAnalytics) FormatOverview() string

FormatOverview returns a comprehensive overview string combining key metrics.

func (*SessionAnalytics) ModelComparison 

func (sa *SessionAnalytics) ModelComparison() string

ModelComparison compares success rate, speed, and cost across models used.

func (*SessionAnalytics) ProductivityScore 

func (sa *SessionAnalytics) ProductivityScore() float64

ProductivityScore returns a composite score (0-100) based on success rate, efficiency (tokens per file modified), and speed.

func (*SessionAnalytics) Record 

func (sa *SessionAnalytics) Record(data SessionData)

Record adds a session data entry to the analytics store.

func (*SessionAnalytics) UsagePatterns 

func (sa *SessionAnalytics) UsagePatterns() []string

UsagePatterns returns human-readable insights about usage behavior.

func (*SessionAnalytics) WeeklyTrend 

func (sa *SessionAnalytics) WeeklyTrend() string

WeeklyTrend shows daily stats for the last 7 days with a sparkline.

type SessionData 

type SessionData struct {
	ID            string        `json:"id"`
	StartTime     time.Time     `json:"start_time"`
	Duration      time.Duration `json:"duration"`
	Model         string        `json:"model"`
	Provider      string        `json:"provider"`
	TokensIn      int           `json:"tokens_in"`
	TokensOut     int           `json:"tokens_out"`
	CostUSD       float64       `json:"cost_usd"`
	ToolCalls     int           `json:"tool_calls"`
	FilesModified int           `json:"files_modified"`
	TestsPassed   bool          `json:"tests_passed"`
	Success       bool          `json:"success"`
	TaskType      string        `json:"task_type"`
}

SessionData holds metrics for a single agent session.

type SessionHealth 

type SessionHealth struct {
	Score   int            `json:"score"`
	Grade   string         `json:"grade"`
	Signals map[string]int `json:"signals"`
}

SessionHealth represents the computed health of a session.

func ComputeSessionHealth 

func ComputeSessionHealth(toolCalls, toolErrors, editRetries, compactions, midTaskCompactions int, outcome string) SessionHealth

ComputeSessionHealth scores a session from 0-100 based on penalty signals.

type SessionStats 

type SessionStats struct {
	TotalSessions   int                   `json:"total_sessions"`
	TotalMessages   int                   `json:"total_messages"`
	TotalDuration   time.Duration         `json:"total_duration"`
	TotalTokens     int64                 `json:"total_tokens"`
	TotalCost       float64               `json:"total_cost"`
	ToolUsage       map[string]int        `json:"tool_usage"`
	ModelUsage      map[string]ModelStats `json:"model_usage"`
	LanguageStats   map[string]int        `json:"language_stats"`
	GitCommits      int                   `json:"git_commits"`
	ActivityHeatmap [7][24]int            `json:"activity_heatmap"` // [weekday][hour]
	PeakDay         time.Weekday          `json:"peak_day"`
	PeakHour        int                   `json:"peak_hour"`
	DateRange       DateRange             `json:"date_range"`
}

SessionStats holds aggregated statistics for a user's sessions.

func ComputeStats 

func ComputeStats(days int) (*SessionStats, error)

ComputeStats aggregates statistics from session event logs.

type SessionSummary 

type SessionSummary struct {
	ID            string        `json:"id"`
	Date          time.Time     `json:"date"`
	Duration      time.Duration `json:"duration"`
	Model         string        `json:"model"`
	Provider      string        `json:"provider"`
	TokensUsed    int           `json:"tokens_used"`
	CostUSD       float64       `json:"cost_usd"`
	ToolCalls     int           `json:"tool_calls"`
	FilesModified int           `json:"files_modified"`
	Success       bool          `json:"success"`
}

SessionSummary captures key metrics for a single session.

type SessionTrace 

type SessionTrace struct {
	SessionID    string    `json:"session_id"`
	StartTime    time.Time `json:"start_time"`
	EndTime      time.Time `json:"end_time,omitempty"`
	Provider     string    `json:"provider"`
	Model        string    `json:"model"`
	MessageCount int       `json:"message_count"`
	ToolCalls    int       `json:"tool_calls"`
	CostUSD      float64   `json:"cost_usd"`
}

SessionTrace tracks session lifecycle events.

func GetTraces 

func GetTraces() ([]*SessionTrace, error)

GetTraces returns all session traces.

type TaskSpend 

type TaskSpend struct {
	TaskType       string  `json:"task_type"`
	TotalCost      float64 `json:"total_cost"`
	Calls          int     `json:"calls"`
	SuggestedModel string  `json:"suggested_model"` // cheaper model that would suffice
}

TaskSpend aggregates cost data for a specific task type.

type TurnCategory 

type TurnCategory string

TurnCategory classifies what a conversation turn was about. 

const (
	CategoryCoding       TurnCategory = "coding"
	CategoryDebugging    TurnCategory = "debugging"
	CategoryTesting      TurnCategory = "testing"
	CategoryExploration  TurnCategory = "exploration"
	CategoryPlanning     TurnCategory = "planning"
	CategoryGitOps       TurnCategory = "git_ops"
	CategoryRefactoring  TurnCategory = "refactoring"
	CategoryConversation TurnCategory = "conversation"
)

func ClassifyTurn 

func ClassifyTurn(toolNames []string, userMessage string) TurnCategory

ClassifyTurn determines the category of a turn from tool names and user message. Deterministic — no LLM calls.

Source Files

View all Source files

Directories

Path Synopsis
Package logger provides structured logging with levels.
 Package logger provides structured logging with levels.
Package metrics provides basic metrics collection (counters, timers, gauges).
 Package metrics provides basic metrics collection (counters, timers, gauges).
Package trace provides Langfuse tracing integration for LLM observability.
 Package trace provides Langfuse tracing integration for LLM observability.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.