analytics

Documentation

Overview

Package analytics provides cost calculation, usage metrics, and anomaly detection.

Index

• type Anomaly
• type AnomalyThresholds
  • func DefaultThresholds() *AnomalyThresholds
• type AnomalyType
• type CostByPeriod
• type Engine
  • func NewEngine(db *sql.DB) *Engine
  • func (e *Engine) CalculateCost(ctx context.Context, provider, model string, ...) (float64, string, error)
  • func (e *Engine) DetectFlowAnomalies(ctx context.Context, flowID string, thresholds *AnomalyThresholds) ([]*Anomaly, error)
  • func (e *Engine) DetectRapidRepeats(ctx context.Context, thresholds *AnomalyThresholds) ([]*Anomaly, error)
  • func (e *Engine) GetCostByDay(ctx context.Context, start, end time.Time) ([]*CostByPeriod, error)
  • func (e *Engine) GetCostByModel(ctx context.Context, start, end time.Time) ([]*CostByPeriod, error)
  • func (e *Engine) GetOverallStats(ctx context.Context, start, end time.Time) (*OverallStats, error)
  • func (e *Engine) GetPricing(ctx context.Context, provider, model string) (*ModelPricing, error)
  • func (e *Engine) GetTaskSummary(ctx context.Context, taskID string) (*TaskSummary, error)
  • func (e *Engine) GetToolStats(ctx context.Context, start, end time.Time) ([]*ToolStats, error)
  • func (e *Engine) ListRecentAnomalies(ctx context.Context, since time.Time, thresholds *AnomalyThresholds) ([]*Anomaly, error)
  • func (e *Engine) ListTaskSummaries(ctx context.Context, start, end time.Time, limit int) ([]*TaskSummary, error)
  • func (e *Engine) SetPricingSource(source *pricing.Source)
• type ModelPricing
• type OverallStats
• type TaskSummary
• type ToolStats

Types

type Anomaly

type Anomaly struct {
	Type        AnomalyType
	FlowID      string
	TaskID      *string
	Timestamp   time.Time
	Severity    string // 'info', 'warning', 'critical'
	Description string
	Value       float64 // The actual value that triggered the anomaly
	Threshold   float64 // The threshold that was exceeded
}

Anomaly represents a detected issue.

type AnomalyThresholds

type AnomalyThresholds struct {
	LargeContextTokens int           // Input tokens above this = large context
	SlowResponseMs     int64         // Duration above this = slow response
	RapidRepeatWindow  time.Duration // Window for detecting rapid repeats
	RapidRepeatCount   int           // Number of similar requests to trigger
	HighCostDollars    float64       // Cost above this = high cost
	ManyToolCallsCount int           // Tool calls above this = many tool calls
}

AnomalyThresholds configures what triggers anomaly detection.

func DefaultThresholds

func DefaultThresholds() *AnomalyThresholds

DefaultThresholds returns sensible default anomaly thresholds.

type AnomalyType

type AnomalyType string

AnomalyType identifies the kind of anomaly detected.

const (
	AnomalyLargeContext  AnomalyType = "large_context"   // Unusually large input token count
	AnomalySlowResponse  AnomalyType = "slow_response"   // Response took longer than threshold
	AnomalyRapidRepeats  AnomalyType = "rapid_repeats"   // Multiple similar requests in short time
	AnomalyHighCost      AnomalyType = "high_cost"       // Single request cost above threshold
	AnomalyToolFailure   AnomalyType = "tool_failure"    // Tool invocation failed
	AnomalyManyToolCalls AnomalyType = "many_tool_calls" // Unusually high tool call count
	AnomalyDroppedEvents AnomalyType = "dropped_events"  // Events were dropped due to backpressure
)

type CostByPeriod

type CostByPeriod struct {
	Period         string // ISO date or hour
	FlowCount      int
	TotalCost      float64
	TotalTokensIn  int
	TotalTokensOut int
}

CostByPeriod represents cost aggregated by time period.

type Engine

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

Engine provides analytics queries and calculations.

func NewEngine

func NewEngine(db *sql.DB) *Engine

NewEngine creates a new analytics engine.

func (*Engine) CalculateCost

func (e *Engine) CalculateCost(ctx context.Context, provider, model string, inputTokens, outputTokens, cacheCreation, cacheRead int) (float64, string, error)

CalculateCost computes the cost for token usage.

func (*Engine) DetectFlowAnomalies

func (e *Engine) DetectFlowAnomalies(ctx context.Context, flowID string, thresholds *AnomalyThresholds) ([]*Anomaly, error)

DetectFlowAnomalies checks a single flow for anomalies.

func (*Engine) DetectRapidRepeats

func (e *Engine) DetectRapidRepeats(ctx context.Context, thresholds *AnomalyThresholds) ([]*Anomaly, error)

DetectRapidRepeats finds flows that look like rapid retries.

func (*Engine) GetCostByDay

func (e *Engine) GetCostByDay(ctx context.Context, start, end time.Time) ([]*CostByPeriod, error)

GetCostByDay returns daily cost breakdown.

func (*Engine) GetCostByModel

func (e *Engine) GetCostByModel(ctx context.Context, start, end time.Time) ([]*CostByPeriod, error)

GetCostByModel returns cost breakdown by model.

func (*Engine) GetOverallStats

func (e *Engine) GetOverallStats(ctx context.Context, start, end time.Time) (*OverallStats, error)

GetOverallStats returns summary statistics for a time range.

func (*Engine) GetPricing

func (e *Engine) GetPricing(ctx context.Context, provider, model string) (*ModelPricing, error)

GetPricing retrieves pricing for a model. It first checks the LiteLLM pricing source, then falls back to the database.

func (*Engine) GetTaskSummary

func (e *Engine) GetTaskSummary(ctx context.Context, taskID string) (*TaskSummary, error)

GetTaskSummary returns aggregated metrics for a task.

func (*Engine) GetToolStats

func (e *Engine) GetToolStats(ctx context.Context, start, end time.Time) ([]*ToolStats, error)

GetToolStats returns aggregated statistics for tools.

func (*Engine) ListRecentAnomalies

func (e *Engine) ListRecentAnomalies(ctx context.Context, since time.Time, thresholds *AnomalyThresholds) ([]*Anomaly, error)

ListRecentAnomalies returns anomalies from recent flows.

func (*Engine) ListTaskSummaries

func (e *Engine) ListTaskSummaries(ctx context.Context, start, end time.Time, limit int) ([]*TaskSummary, error)

ListTaskSummaries returns summaries for all tasks in a time range.

func (*Engine) SetPricingSource

func (e *Engine) SetPricingSource(source *pricing.Source)

SetPricingSource sets the LiteLLM pricing source for cost calculations.

type ModelPricing

type ModelPricing struct {
	Provider           string
	ModelPattern       string
	InputCostPer1k     float64
	OutputCostPer1k    float64
	CacheCreationPer1k *float64
	CacheReadPer1k     *float64
	EffectiveDate      time.Time
}

ModelPricing contains pricing data for a model.

type OverallStats

type OverallStats struct {
	TotalFlows       int
	TotalCost        float64
	TotalTokensIn    int
	TotalTokensOut   int
	TotalTasks       int
	TotalToolCalls   int
	AvgCostPerFlow   float64
	AvgTokensPerFlow float64
}

OverallStats represents summary statistics.

type TaskSummary

type TaskSummary struct {
	TaskID         string
	FlowCount      int
	TotalTokensIn  int
	TotalTokensOut int
	TotalCost      float64
	FirstSeen      time.Time
	LastSeen       time.Time
	DurationMs     int64 // Wall clock time from first to last
	Models         []string
	ToolsUsed      []string
}

TaskSummary represents aggregated statistics for a task.

type ToolStats

type ToolStats struct {
	ToolName        string
	InvocationCount int
	SuccessCount    int
	FailureCount    int
	SuccessRate     float64
	TotalCost       float64
	AvgDurationMs   float64
	TotalTokensIn   int
	TotalTokensOut  int
}

ToolStats represents statistics for a tool.