stats

Documentation

Index

• func DefaultFilePath() string
• func GetXSQLAttrEnv() string
• func ParseAttrs(cliAttrs []string, envAttr string) map[string]string
• func ValidateAttr(key, value string) error
• func ValidateAttrs(attrs map[string]string) error
• type AggregatedRecord
  • func Query(records []*Record, filter Filter) []*AggregatedRecord
• type Filter
• type LogResult
• type Record
• type StatsConfig
• type StatsLogTableFormatter
  • func (f *StatsLogTableFormatter) ToTableData() ([]string, []map[string]any, bool)
• type StatsResult
• type StatsTableFormatter
  • func (f *StatsTableFormatter) ToTableData() ([]string, []map[string]any, bool)
• type Store
  • func NewStore(path string) *Store
  • func (s *Store) Append(r *Record) error
  • func (s *Store) Cleanup(retentionDays int) (int, error)
  • func (s *Store) Load() ([]*Record, error)
  • func (s *Store) Reset() error

Functions

func DefaultFilePath

func DefaultFilePath() string

DefaultFilePath returns the default stats file path.

func GetXSQLAttrEnv

func GetXSQLAttrEnv() string

GetXSQLAttrEnv returns the value of XSQL_ATTR environment variable.

func ParseAttrs

func ParseAttrs(cliAttrs []string, envAttr string) map[string]string

ParseAttrs parses attributes from CLI flags and ENV. CLI flags take precedence over ENV. ENV format: "key1=val1,key2=val2"

func ValidateAttr

func ValidateAttr(key, value string) error

ValidateAttr validates a single attribute key and value.

func ValidateAttrs

func ValidateAttrs(attrs map[string]string) error

ValidateAttrs validates all attributes.

Types

type AggregatedRecord

type AggregatedRecord struct {
	Cmd     string            `json:"cmd"`
	Profile string            `json:"profile"`
	Attrs   map[string]string `json:"attrs,omitempty"`
	OK      int               `json:"ok"`
	Fail    int               `json:"fail"`
	AvgMs   int64             `json:"avg_ms"`
}

AggregatedRecord is an aggregated statistics entry.

func Query

func Query(records []*Record, filter Filter) []*AggregatedRecord

Query aggregates records by cmd × profile × attrs.

type Filter

type Filter struct {
	Profile string
	Cmd     string
	Attrs   map[string]string
	Since   *time.Time
	Until   *time.Time
}

Filter defines the query filter for stats aggregation.

type LogResult

type LogResult struct {
	Records []Record `json:"records" yaml:"records"`
	Total   int      `json:"total" yaml:"total"`
}

LogResult is the output of stats log.

type Record

type Record struct {
	Timestamp  time.Time         `json:"ts"`
	Cmd        string            `json:"cmd"`
	Profile    string            `json:"profile"`
	OK         bool              `json:"ok"`
	DurationMs int64             `json:"duration_ms"`
	ErrorCode  string            `json:"error_code,omitempty"`
	SQL        string            `json:"sql,omitempty"`
	Attrs      map[string]string `json:"attrs,omitempty"`
}

Record is a single usage statistics entry.

type StatsConfig

type StatsConfig struct {
	Enabled       bool   `yaml:"enabled" json:"enabled"`
	LogSQL        bool   `yaml:"log_sql" json:"log_sql"`
	FilePath      string `yaml:"file_path" json:"file_path,omitempty"`
	RetentionDays int    `yaml:"retention_days" json:"retention_days,omitempty"`
}

StatsConfig holds the statistics configuration.

type StatsLogTableFormatter

type StatsLogTableFormatter struct {
	Records []Record
}

StatsLogTableFormatter implements output.TableFormatter for stats log.

func (*StatsLogTableFormatter) ToTableData

func (f *StatsLogTableFormatter) ToTableData() ([]string, []map[string]any, bool)

ToTableData returns table columns and rows for stats log.

type StatsResult

type StatsResult struct {
	Records []*AggregatedRecord `json:"records" yaml:"records"`
}

StatsResult is the output of stats aggregation.

type StatsTableFormatter

type StatsTableFormatter struct {
	Records []*AggregatedRecord
}

StatsTableFormatter implements output.TableFormatter for stats aggregation.

func (*StatsTableFormatter) ToTableData

func (f *StatsTableFormatter) ToTableData() ([]string, []map[string]any, bool)

ToTableData returns table columns and rows for stats aggregation.

type Store

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

Store manages the JSONL stats file.

func NewStore

func NewStore(path string) *Store

NewStore creates a stats store with the given path. If path is empty, uses the default path. Supports ~ expansion to user home directory.

func (*Store) Append

func (s *Store) Append(r *Record) error

Append atomically appends a record to the JSONL file.

func (*Store) Cleanup

func (s *Store) Cleanup(retentionDays int) (int, error)

Cleanup removes records older than retentionDays.

func (*Store) Load

func (s *Store) Load() ([]*Record, error)

Load reads all records from the JSONL file.

func (*Store) Reset

func (s *Store) Reset() error

Reset clears the stats file.