report

package
v6.2.1 Latest Latest
Warning

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

Go to latest
Published: Oct 26, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package report defines Stroppy's versioned machine-readable run report.

Index

Constants

View Source
const (
	// SchemaVersion is the current run report envelope version.
	SchemaVersion = 4
	// Kind identifies a benchmark run report among future report families.
	Kind = "run"
)
View Source
const CaptureSchema = 1

Variables

View Source
var ErrCaptureArtifact = errors.New("invalid capture artifact")
View Source
var (
	ErrInvalidHistoryID = errors.New("invalid report history ID")
)

Functions

func CaptureRoot

func CaptureRoot(base string, capture *Capture) (*os.Root, error)

CaptureRoot resolves a real UUID recording directory relative to a report.

func CaptureState

func CaptureState(base string, c *Capture) string

CaptureState distinguishes interrupted and missing recordings from final reports.

func OpenCaptureFile

func OpenCaptureFile(base string, capture *Capture, name string) (*os.File, error)

OpenCaptureFile opens only declared regular files and rejects replacement links.

func OutputOverwritesCapture

func OutputOverwritesCapture(path, base string, c *Capture) (bool, error)

OutputOverwritesCapture rejects destinations aliased to recording data.

func PortableCaptureJSON

func PortableCaptureJSON(data []byte) ([]byte, error)

PortableCaptureJSON preserves report fields while making recording references relative.

func ReadCaptureFile

func ReadCaptureFile(base string, capture *Capture, name string) ([]byte, error)

ReadCaptureFile retrieves a complete declared recording artifact.

func RemoveCapture

func RemoveCapture(base string, c *Capture) error

RemoveCapture removes only the declared UUID directory and known recording files.

func SameOutput

func SameOutput(a, b string) (bool, error)

SameOutput reports whether two paths publish to the same directory entry. Existing identities also catch case-insensitive names and hard-link aliases.

func Save

func Save(run *Run) (string, error)

Save stores one run report under ~/.stroppy/reports and returns its path.

func WriteBundle

func WriteBundle(output io.Writer, data []byte, base string) error

WriteBundle streams complete JSON and artifacts to a portable ZIP.

func WriteBundleInto

func WriteBundleInto(archive *zip.Writer, data []byte, base string) error

WriteBundleInto appends portable report JSON and complete streams to an owned ZIP writer.

Types

type Capture

type Capture struct {
	Schema          int                      `json:"schema"`
	ID              string                   `json:"id"`
	SourceID        string                   `json:"source_id,omitempty"`
	ReportID        string                   `json:"report_id,omitempty"`
	RunID           string                   `json:"run_id,omitempty"`
	Directory       string                   `json:"directory"`
	State           string                   `json:"state"`
	StartedAt       time.Time                `json:"started_at"`
	FinishedAt      time.Time                `json:"finished_at,omitzero"`
	IntervalSeconds float64                  `json:"interval_seconds"`
	MissedSamples   uint64                   `json:"missed_samples"`
	Streams         map[string]CaptureStream `json:"streams"`
	Owner           string                   `json:"owner,omitempty"`
}

Capture identifies independently versioned append-only run artifacts.

func CaptureFromJSON

func CaptureFromJSON(data []byte) (*Capture, error)

CaptureFromJSON decodes only the optional recording envelope.

type CaptureEvent

type CaptureEvent struct {
	Time            time.Time `json:"time"`
	ElapsedSeconds  float64   `json:"elapsed_seconds"`
	Kind            string    `json:"kind"`
	Step            string    `json:"step,omitempty"`
	State           string    `json:"state,omitempty"`
	Workers         int       `json:"workers,omitempty"`
	DurationSeconds float64   `json:"duration_seconds,omitempty"`
	DrainSeconds    float64   `json:"drain_seconds,omitempty"`
}

CaptureEvent identifies execution boundaries using the capture clock.

type CaptureStream

type CaptureStream struct {
	File      string `json:"file"`
	Enabled   bool   `json:"enabled"`
	Records   uint64 `json:"records"`
	Bytes     int64  `json:"bytes"`
	MaxBytes  int64  `json:"max_bytes"`
	Dropped   uint64 `json:"dropped"`
	Truncated uint64 `json:"truncated"`
	Error     string `json:"error,omitempty"`
}

CaptureStream describes bounded recording and any loss of data.

type CapturedLog

type CapturedLog struct {
	CaptureID      string          `json:"capture_id"`
	ReportID       string          `json:"report_id,omitempty"`
	Time           time.Time       `json:"time"`
	ElapsedSeconds float64         `json:"elapsed_seconds"`
	Level          string          `json:"level"`
	Logger         string          `json:"logger"`
	Message        string          `json:"message"`
	Fields         json.RawMessage `json:"fields"`
}

CapturedLog keeps structured fields alongside available execution correlation.

type Driver

type Driver struct {
	Name string `json:"name"`
	Type string `json:"type"`
}

Driver identifies one configured driver without persisting connection data.

type ErrorGroup

type ErrorGroup struct {
	Operation string `json:"operation"`
	Class     string `json:"class"`
	Count     uint64 `json:"count"`
}

ErrorGroup is one representative operation and driver-independent class.

type ErrorSummary

type ErrorSummary struct {
	TerminalErrors   uint64       `json:"terminal_errors"`
	FailedIterations uint64       `json:"failed_iterations"`
	FailedQueries    uint64       `json:"failed_queries"`
	RetryAttempts    uint64       `json:"retry_attempts"`
	Groups           []ErrorGroup `json:"groups"`
}

ErrorSummary contains bounded nonfatal terminal error groups.

type Execution

type Execution struct {
	Executor            string   `json:"executor"`
	Workers             int      `json:"workers"`
	Iterations          int64    `json:"iterations,omitempty"`
	DurationSeconds     float64  `json:"duration_seconds,omitempty"`
	DrainTimeoutSeconds *float64 `json:"drain_timeout_seconds"`
	DrainUnlimited      bool     `json:"drain_unlimited,omitempty"`
	MeasurementSeconds  float64  `json:"measurement_seconds"`
	DrainSeconds        float64  `json:"drain_seconds,omitempty"`
}

Execution records the configured policy and actual completion window of a step.

type Failure

type Failure struct {
	Phase  string `json:"phase"`
	Reason string `json:"reason"`
}

Failure identifies the lifecycle phase that prevented clean completion.

type History

type History struct {
	Directory string
}

History manages run reports in one directory. Filenames identify stored reports independently of the report's potentially user-supplied ID.

func DefaultHistory

func DefaultHistory() (*History, error)

DefaultHistory resolves the run history without creating it.

func (*History) Artifact

func (h *History) Artifact(id, name string) ([]byte, error)

Artifact retrieves a complete artifact as data for programmatic callers.

func (*History) Bundle

func (h *History) Bundle(output io.Writer, id string) error

Bundle exports saved JSON and its complete capture streams.

func (*History) CheckRemoval

func (h *History) CheckRemoval(ids []string) error

CheckRemoval validates every explicit target before a batch removal starts.

func (*History) Get

func (h *History) Get(id string) ([]byte, error)

Get returns the original JSON, including unknown fields and workload payloads.

func (*History) List

func (h *History) List(query HistoryQuery) ([]HistoryEntry, []HistoryProblem, error)

List orders matching entries by start time, then history ID.

func (*History) OpenArtifact

func (h *History) OpenArtifact(id, name string) (*os.File, error)

OpenArtifact retrieves a declared artifact by history identity without buffering it.

func (*History) Remove

func (h *History) Remove(id string) error

Remove deletes only regular files with managed history names. Corrupt reports can be removed explicitly without decoding their payload.

func (*History) RemoveSelected

func (h *History) RemoveSelected(entries []HistoryEntry) ([]string, error)

RemoveSelected removes only unchanged files from the selected history root.

func (*History) Save

func (h *History) Save(run *Run) (path string, err error)

Save publishes a complete report without replacing an existing entry.

func (*History) SelectRemoval

func (h *History) SelectRemoval(ids []string) ([]HistoryEntry, error)

SelectRemoval snapshots explicit targets, including corrupt regular reports.

func (*History) Status

func (h *History) Status() (HistoryStatus, error)

Status inspects storage without creating the directory.

type HistoryEntry

type HistoryEntry struct {
	ID           string    `json:"id"`
	ReportID     string    `json:"report_id"`
	RunID        string    `json:"run_id,omitempty"`
	Schema       int       `json:"schema"`
	StartedAt    time.Time `json:"started_at"`
	FinishedAt   time.Time `json:"finished_at"`
	Workload     string    `json:"workload"`
	Driver       string    `json:"driver"`
	Drivers      []Driver  `json:"drivers"`
	Status       Status    `json:"status"`
	TPS          *float64  `json:"tps,omitempty"`
	CaptureState string    `json:"capture_state,omitempty"`
	SizeBytes    int64     `json:"size_bytes"`
	// contains filtered or unexported fields
}

HistoryEntry is common metadata, not a workload-specific result projection.

type HistoryProblem

type HistoryProblem struct {
	ID    string `json:"id"`
	Error string `json:"error"`
}

HistoryProblem identifies an unreadable entry without hiding healthy entries.

type HistoryQuery

type HistoryQuery struct {
	Workloads []string
	Drivers   []string
	Statuses  []Status
	Since     time.Time
	Until     time.Time
	OlderThan time.Time
	Reverse   bool
	Limit     int
}

HistoryQuery applies OR within each field and AND across fields. Since is inclusive, Until is exclusive, and Limit zero returns all matching entries.

type HistoryStatus

type HistoryStatus struct {
	Directory  string           `json:"directory"`
	Exists     bool             `json:"exists"`
	Reports    int              `json:"reports"`
	Unreadable int              `json:"unreadable"`
	SizeBytes  int64            `json:"size_bytes"`
	Problems   []HistoryProblem `json:"problems"`
}

HistoryStatus describes local storage, including entries that need attention.

type Host

type Host struct {
	OS        string `json:"os"`
	Arch      string `json:"arch"`
	GoVersion string `json:"go_version"`
	CPUs      int    `json:"cpus"`
	MaxProcs  int    `json:"gomaxprocs"`
}

Host fingerprints the runtime environment used for a run.

type Metric

type Metric struct {
	Type         string             `json:"type"`
	Unit         string             `json:"unit,omitempty"`
	Total        *float64           `json:"total,omitempty"`
	Count        *uint64            `json:"count,omitempty"`
	Sum          *float64           `json:"sum,omitempty"`
	Average      *float64           `json:"average,omitempty"`
	Bounds       []float64          `json:"bounds,omitempty"`
	BucketCounts []uint64           `json:"bucket_counts,omitempty"`
	Percentiles  map[string]float64 `json:"percentiles,omitempty"`
	Series       []MetricSeries     `json:"series,omitempty"`
}

Metric is a stable projection of one OpenTelemetry metric. Aggregate values stay convenient for scripts while Series preserves point dimensions.

type MetricSample

type MetricSample struct {
	Sequence          uint64            `json:"sequence"`
	CaptureID         string            `json:"capture_id"`
	ReportID          string            `json:"report_id,omitempty"`
	Time              time.Time         `json:"time"`
	ElapsedSeconds    float64           `json:"elapsed_seconds"`
	CollectionSeconds float64           `json:"collection_seconds"`
	Semantics         string            `json:"semantics"`
	Metrics           map[string]Metric `json:"metrics"`
}

MetricSample is a cumulative counter/histogram or recorded gauge snapshot.

type MetricSeries

type MetricSeries struct {
	Attributes   map[string]any `json:"attributes,omitempty"`
	Total        *float64       `json:"total,omitempty"`
	Count        *uint64        `json:"count,omitempty"`
	Sum          *float64       `json:"sum,omitempty"`
	Average      *float64       `json:"average,omitempty"`
	Bounds       []float64      `json:"bounds,omitempty"`
	BucketCounts []uint64       `json:"bucket_counts,omitempty"`
}

MetricSeries is one dimensioned counter, gauge, or histogram point.

type Parameter

type Parameter struct {
	Value  any    `json:"value"`
	Source string `json:"source"`
}

Parameter is one effective typed value and its winning input source.

type Parameters

type Parameters struct {
	Run      map[string]Parameter `json:"run"`
	Workload map[string]Parameter `json:"workload"`
}

Parameters separates shared run inputs from workload-owned inputs.

type Run

type Run struct {
	Schema             int                  `json:"schema"`
	Kind               string               `json:"kind"`
	ID                 string               `json:"id"`
	RunID              string               `json:"run_id,omitempty"`
	StroppyVersion     string               `json:"stroppy_version"`
	BuildDigest        string               `json:"build_digest,omitempty"`
	StartedAt          time.Time            `json:"started_at"`
	FinishedAt         time.Time            `json:"finished_at"`
	Status             Status               `json:"status"`
	Workload           string               `json:"workload"`
	Driver             string               `json:"driver"`
	Drivers            []Driver             `json:"drivers"`
	Metadata           map[string]string    `json:"metadata,omitempty"`
	Custom             map[string]string    `json:"custom,omitempty"`
	Host               Host                 `json:"host"`
	Scenario           Scenario             `json:"scenario"`
	Parameters         Parameters           `json:"parameters"`
	StepSelection      StepSelection        `json:"step_selection"`
	Steps              []Step               `json:"steps"`
	Measurements       map[string]float64   `json:"measurements"`
	Executions         map[string]Execution `json:"executions"`
	MeasurementSeconds float64              `json:"measurement_seconds"`
	Metrics            map[string]Metric    `json:"metrics"`
	Errors             ErrorSummary         `json:"errors"`
	Failure            *Failure             `json:"failure,omitempty"`
	WorkloadReports    []WorkloadReport     `json:"workload_reports"`
	Capture            *Capture             `json:"capture,omitempty"`
}

Run is one complete benchmark result. WorkloadReports remain opaque to the common envelope so new workload payloads do not require storage migrations.

func AttachCapture

func AttachCapture(run *Run, base, destination string) (result *Run, err error)

type Scenario

type Scenario struct {
	Executor            string   `json:"executor"`
	VUs                 int      `json:"vus"`
	DurationSeconds     *float64 `json:"duration_seconds"`
	IterationsRequested *int64   `json:"iterations_requested"`
}

Scenario contains effective executor settings.

type Status

type Status string

Status describes how a run terminated.

const (
	StatusCompleted           Status = "completed"
	StatusCompletedWithErrors Status = "completed_with_errors"
	StatusFailed              Status = "failed"
	StatusCanceled            Status = "canceled"
)

type Step

type Step struct {
	Name            string  `json:"name"`
	Status          string  `json:"status"`
	Executions      uint64  `json:"executions"`
	DurationSeconds float64 `json:"duration_seconds,omitempty"`
}

Step is one step observed by the workload runtime.

type StepSelection

type StepSelection struct {
	Only    []string `json:"only"`
	Exclude []string `json:"exclude"`
}

StepSelection records explicit step filters.

type WorkloadReport

type WorkloadReport struct {
	Kind   string               `json:"kind"`
	Schema int                  `json:"schema"`
	Status WorkloadReportStatus `json:"status"`
	Reason string               `json:"reason,omitempty"`
	Data   json.RawMessage      `json:"data,omitempty"`
}

WorkloadReport is a typed, independently versioned workload contribution.

type WorkloadReportStatus

type WorkloadReportStatus string

WorkloadReportStatus describes one workload-owned report contribution.

const (
	WorkloadReportOK      WorkloadReportStatus = "ok"
	WorkloadReportSkipped WorkloadReportStatus = "skipped"
	WorkloadReportError   WorkloadReportStatus = "error"
	WorkloadReportMissing WorkloadReportStatus = "missing"
)

Directories

Path Synopsis
Package compare calculates explicit, dimension-preserving comparisons of saved runs.
Package compare calculates explicit, dimension-preserving comparisons of saved runs.
Package view renders saved run reports without changing their data.
Package view renders saved run reports without changing their data.

Jump to

Keyboard shortcuts

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