Documentation
¶
Overview ¶
Package report defines Stroppy's versioned machine-readable run report.
Index ¶
- Constants
- Variables
- func CaptureRoot(base string, capture *Capture) (*os.Root, error)
- func CaptureState(base string, c *Capture) string
- func OpenCaptureFile(base string, capture *Capture, name string) (*os.File, error)
- func OutputOverwritesCapture(path, base string, c *Capture) (bool, error)
- func PortableCaptureJSON(data []byte) ([]byte, error)
- func ReadCaptureFile(base string, capture *Capture, name string) ([]byte, error)
- func RemoveCapture(base string, c *Capture) error
- func SameOutput(a, b string) (bool, error)
- func Save(run *Run) (string, error)
- func WriteBundle(output io.Writer, data []byte, base string) error
- func WriteBundleInto(archive *zip.Writer, data []byte, base string) error
- type Capture
- type CaptureEvent
- type CaptureStream
- type CapturedLog
- type Driver
- type ErrorGroup
- type ErrorSummary
- type Execution
- type Failure
- type History
- func (h *History) Artifact(id, name string) ([]byte, error)
- func (h *History) Bundle(output io.Writer, id string) error
- func (h *History) CheckRemoval(ids []string) error
- func (h *History) Get(id string) ([]byte, error)
- func (h *History) List(query HistoryQuery) ([]HistoryEntry, []HistoryProblem, error)
- func (h *History) OpenArtifact(id, name string) (*os.File, error)
- func (h *History) Remove(id string) error
- func (h *History) RemoveSelected(entries []HistoryEntry) ([]string, error)
- func (h *History) Save(run *Run) (path string, err error)
- func (h *History) SelectRemoval(ids []string) ([]HistoryEntry, error)
- func (h *History) Status() (HistoryStatus, error)
- type HistoryEntry
- type HistoryProblem
- type HistoryQuery
- type HistoryStatus
- type Host
- type Metric
- type MetricSample
- type MetricSeries
- type Parameter
- type Parameters
- type Run
- type Scenario
- type Status
- type Step
- type StepSelection
- type WorkloadReport
- type WorkloadReportStatus
Constants ¶
const ( // SchemaVersion is the current run report envelope version. SchemaVersion = 4 // Kind identifies a benchmark run report among future report families. Kind = "run" )
const CaptureSchema = 1
Variables ¶
var ErrCaptureArtifact = errors.New("invalid capture artifact")
var (
ErrInvalidHistoryID = errors.New("invalid report history ID")
)
Functions ¶
func CaptureRoot ¶
CaptureRoot resolves a real UUID recording directory relative to a report.
func CaptureState ¶
CaptureState distinguishes interrupted and missing recordings from final reports.
func OpenCaptureFile ¶
OpenCaptureFile opens only declared regular files and rejects replacement links.
func OutputOverwritesCapture ¶
OutputOverwritesCapture rejects destinations aliased to recording data.
func PortableCaptureJSON ¶
PortableCaptureJSON preserves report fields while making recording references relative.
func ReadCaptureFile ¶
ReadCaptureFile retrieves a complete declared recording artifact.
func RemoveCapture ¶
RemoveCapture removes only the declared UUID directory and known recording files.
func SameOutput ¶
SameOutput reports whether two paths publish to the same directory entry. Existing identities also catch case-insensitive names and hard-link aliases.
func WriteBundle ¶
WriteBundle streams complete JSON and artifacts to a portable ZIP.
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 ¶
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 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"`
StartupSeconds float64 `json:"startup_seconds,omitempty"`
DrainSeconds float64 `json:"drain_seconds,omitempty"`
}
Execution records the configured policy and actual completion window of a step.
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 ¶
DefaultHistory resolves the run history without creating it.
func (*History) CheckRemoval ¶
CheckRemoval validates every explicit target before a batch removal starts.
func (*History) Get ¶
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 ¶
OpenArtifact retrieves a declared artifact by history identity without buffering it.
func (*History) Remove ¶
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) 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 ¶
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 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.
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 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 ¶
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" )
Source Files
¶
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. |