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 ¶
- type Eval
- type EvalMetrics
- type EvalRun
- type MemoryStorage
- func (m *MemoryStorage) CalculateEvalMetrics(ctx context.Context, evalID string) (*EvalMetrics, error)
- func (m *MemoryStorage) Close() error
- func (m *MemoryStorage) CreateEval(ctx context.Context, eval *Eval) error
- func (m *MemoryStorage) CreateEvalRun(ctx context.Context, run *EvalRun) error
- func (m *MemoryStorage) GetStats() map[string]int
- func (m *MemoryStorage) UpdateEvalStatus(ctx context.Context, evalID string, status string) error
- func (m *MemoryStorage) UpsertEvalMetrics(ctx context.Context, metrics *EvalMetrics) error
- type SQLiteStorage
- func (s *SQLiteStorage) CalculateEvalMetrics(ctx context.Context, evalID string) (*EvalMetrics, error)
- func (s *SQLiteStorage) Close() error
- func (s *SQLiteStorage) CreateEval(ctx context.Context, eval *Eval) error
- func (s *SQLiteStorage) CreateEvalRun(ctx context.Context, run *EvalRun) error
- func (s *SQLiteStorage) UpdateEvalStatus(ctx context.Context, evalID string, status string) error
- func (s *SQLiteStorage) UpsertEvalMetrics(ctx context.Context, metrics *EvalMetrics) error
- type Storage
- type StorageConfig
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 ¶
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 (*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 ¶
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