storage

package
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Feb 5, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

Documentation

Overview

Package storage provides in-process trace storage for embedded observability.

This package implements self-contained memory and SQLite storage backends for storing traces, metrics, and evaluation data. It replaces the external Hawk dependency with lightweight, self-contained implementations.

Storage Backends:

Memory Storage:

  • Ring buffer with configurable size (default: 10,000 traces)
  • Thread-safe with RWMutex
  • Automatic FIFO eviction when full
  • Fast lookups by trace ID
  • Suitable for development, testing, and short-lived processes

SQLite Storage:

  • Persistent storage with indexed queries
  • Connection pooling for concurrent access
  • Requires -tags fts5 build flag
  • Suitable for production use and long-term storage

Usage Example:

// Create memory storage
storage := storage.NewMemoryStorage(10000)
defer storage.Close()

// Or create SQLite storage (requires -tags fts5)
storage, err := storage.NewSQLiteStorage("/path/to/traces.db")
if err != nil {
	log.Fatal(err)
}
defer storage.Close()

// Store an evaluation
eval := &storage.Eval{
	ID:     "eval-123",
	Name:   "My Evaluation",
	Suite:  "test-suite",
	Status: "running",
}
err = storage.CreateEval(ctx, eval)

// Store a trace/span
run := &storage.EvalRun{
	ID:              "run-456",
	EvalID:          "eval-123",
	Query:           "What is 2+2?",
	Model:           "claude-sonnet-4",
	Response:        "4",
	ExecutionTimeMS: 150,
	TokenCount:      25,
	Success:         true,
}
err = storage.CreateEvalRun(ctx, run)

// Calculate and store metrics
metrics, err := storage.CalculateEvalMetrics(ctx, "eval-123")
err = storage.UpsertEvalMetrics(ctx, metrics)

Package storage provides in-process trace storage for embedded observability. This package implements self-contained memory and SQLite storage backends for storing traces, metrics, and evaluation data without external dependencies.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Eval

type Eval struct {
	ID        string // Unique evaluation ID
	Name      string // Human-readable name
	Suite     string // Suite or category name
	Status    string // Status: "running", "completed", "failed"
	CreatedAt int64  // Unix timestamp
	UpdatedAt int64  // Unix timestamp
}

Eval represents an evaluation session (grouping of related traces)

type EvalMetrics

type EvalMetrics struct {
	EvalID             string  // Evaluation ID
	TotalRuns          int32   // Total number of runs
	SuccessfulRuns     int32   // Number of successful runs
	FailedRuns         int32   // Number of failed runs
	SuccessRate        float64 // Success rate (0.0-1.0)
	AvgExecutionTimeMS float64 // Average execution time
	TotalTokens        int64   // Total tokens used
	AvgTokensPerRun    float64 // Average tokens per run
	TotalCost          float64 // Total estimated cost (if available)
	FirstRunTimestamp  int64   // Timestamp of first run
	LastRunTimestamp   int64   // Timestamp of last run
	UpdatedAt          int64   // When metrics were last updated
}

EvalMetrics represents aggregated metrics for an evaluation

type EvalRun

type EvalRun struct {
	ID                string // Unique span ID
	EvalID            string // Evaluation this run belongs to
	Query             string // Input query/prompt
	Model             string // LLM model used
	ConfigurationJSON string // JSON-encoded configuration/attributes
	Response          string // Output response
	ExecutionTimeMS   int64  // Execution duration in milliseconds
	TokenCount        int32  // Total tokens used
	Success           bool   // Whether execution succeeded
	ErrorMessage      string // Error message if failed
	SessionID         string // Session ID for grouping
	Timestamp         int64  // Unix timestamp
}

EvalRun represents a single trace/span within an evaluation

type MemoryStorage

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

MemoryStorage provides in-memory trace storage with ring buffer eviction. Thread-safe for concurrent access. Suitable for development and testing.

func NewMemoryStorage

func NewMemoryStorage(maxTraces int) *MemoryStorage

NewMemoryStorage creates a new in-memory storage backend

func (*MemoryStorage) CalculateEvalMetrics

func (m *MemoryStorage) CalculateEvalMetrics(ctx context.Context, evalID string) (*EvalMetrics, error)

CalculateEvalMetrics calculates aggregated metrics for an evaluation

func (*MemoryStorage) Close

func (m *MemoryStorage) Close() error

Close closes the memory storage (no-op for memory storage)

func (*MemoryStorage) CreateEval

func (m *MemoryStorage) CreateEval(ctx context.Context, eval *Eval) error

CreateEval creates a new evaluation session

func (*MemoryStorage) CreateEvalRun

func (m *MemoryStorage) CreateEvalRun(ctx context.Context, run *EvalRun) error

CreateEvalRun stores a new trace/span

func (*MemoryStorage) GetStats

func (m *MemoryStorage) GetStats() map[string]int

GetStats returns current storage statistics (for testing/debugging)

func (*MemoryStorage) UpdateEvalStatus

func (m *MemoryStorage) UpdateEvalStatus(ctx context.Context, evalID string, status string) error

UpdateEvalStatus updates the status of an evaluation

func (*MemoryStorage) UpsertEvalMetrics

func (m *MemoryStorage) UpsertEvalMetrics(ctx context.Context, metrics *EvalMetrics) error

UpsertEvalMetrics stores or updates metrics for an evaluation

type SQLiteStorage

type SQLiteStorage struct{}

SQLiteStorage is a stub type when built without fts5

func (*SQLiteStorage) CalculateEvalMetrics

func (s *SQLiteStorage) CalculateEvalMetrics(ctx context.Context, evalID string) (*EvalMetrics, error)

func (*SQLiteStorage) Close

func (s *SQLiteStorage) Close() error

func (*SQLiteStorage) CreateEval

func (s *SQLiteStorage) CreateEval(ctx context.Context, eval *Eval) error

These stub methods ensure SQLiteStorage implements Storage interface

func (*SQLiteStorage) CreateEvalRun

func (s *SQLiteStorage) CreateEvalRun(ctx context.Context, run *EvalRun) error

func (*SQLiteStorage) UpdateEvalStatus

func (s *SQLiteStorage) UpdateEvalStatus(ctx context.Context, evalID string, status string) error

func (*SQLiteStorage) UpsertEvalMetrics

func (s *SQLiteStorage) UpsertEvalMetrics(ctx context.Context, metrics *EvalMetrics) error

type Storage

type Storage interface {
	// Eval operations
	CreateEval(ctx context.Context, eval *Eval) error
	UpdateEvalStatus(ctx context.Context, evalID string, status string) error

	// EvalRun operations (trace/span storage)
	CreateEvalRun(ctx context.Context, run *EvalRun) error

	// Metrics operations
	CalculateEvalMetrics(ctx context.Context, evalID string) (*EvalMetrics, error)
	UpsertEvalMetrics(ctx context.Context, metrics *EvalMetrics) error

	// Lifecycle
	Close() error
}

Storage provides in-process trace storage for embedded observability. Implementations must be thread-safe for concurrent access.

func NewSQLiteStorage

func NewSQLiteStorage(dbPath string) (Storage, error)

NewSQLiteStorage returns an error when built without fts5 support

func NewStorage

func NewStorage(config *StorageConfig) (Storage, error)

NewStorage creates a new storage backend based on configuration

type StorageConfig

type StorageConfig struct {
	// Type: "memory" or "sqlite"
	Type string

	// Path: SQLite database file path (required if Type = "sqlite")
	Path string

	// MaxMemoryTraces: Maximum traces to keep in memory storage (default: 10,000)
	// Only used for memory storage
	MaxMemoryTraces int
}

StorageConfig configures storage backend creation

func DefaultStorageConfig

func DefaultStorageConfig() *StorageConfig

DefaultStorageConfig returns sensible defaults

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL