sampleframe

package
v0.1.78 Latest Latest
Warning

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

Go to latest
Published: Nov 19, 2026 License: Apache-2.0 Imports: 16 Imported by: 1

README

Completed samples

Writer commits an unkeyed stream's rows and completion metadata together through BatchAppender. A successful empty sample is a real frame. Invalid counts, time bounds, row validation failures and atomic write failures return an error and publish no completion metadata. The writer requires exclusive ownership of the primary stream; process collectors that already have an atomic batch should append a Frame to that same batch instead.

writer := sampleframe.Writer{Backend: backend, Schema: schema, Stream: stream}
frame, err := writer.Append(ctx, sampleframe.Frame{
    Source: "worker-1/heap",
    StartedAt: started,
    CompletedAt: completed,
    Observed: len(observed),
    Limit: captureLimit,
}, retainedRows)
if err != nil {
    return err
}

Source identifies one endpoint or process/profile lifetime. StartedAt and CompletedAt describe the collection interval. Observed counts rows before capture truncation and Limit is that capture's cap, with zero meaning unlimited. Summary carries producer metadata such as original query columns and ordering. The writer sets ID, AfterSeq, ToSeq and Retained; readers select a frame before applying viewer filters. Frame membership is the primary stream's sequence window (AfterSeq, ToSeq], including when both bounds are equal. Metadata is stored in <stream>-frames. Call Close after the final checkpoint to seal completion metadata without inventing a sample.

BuildHierarchy accepts root-first stacks with exclusive numeric leaf weights, including fractional process CPU. It computes cumulative totals, preserves recursion, rejects invalid weights, and gives nodes stable identities by their complete path. Optional IDs distinguish ownership nodes with identical labels; when supplied they must match Frames one for one. JSON numbers have the precision of the consuming renderer; native record values remain available separately for exact exports and filters.

From the recordstore module:

go test ./sampleframe ./recordresults

The tests use isolated SQLite stores and cover empty frames, atomic validation failure, identical timestamps, sealing and hierarchy conservation.

Documentation

Overview

Package sampleframe publishes completed samples with their exact row windows.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Schema

func Schema(kind string) (recordstore.KindSchema, error)

Types

type Backend

type Backend interface {
	recordstore.BatchAppender
	Meta(context.Context, string) (recordstore.Meta, error)
}

type Frame

type Frame struct {
	Error       string         `json:"error,omitempty"`
	Result      string         `json:"result,omitempty"`
	Tick        int64          `json:"tick,omitempty"`
	ID          string         `json:"id" filter:"exact"`
	Source      string         `json:"source" filter:"terms"`
	StartedAt   time.Time      `json:"startedAt"`
	CompletedAt time.Time      `json:"completedAt"`
	AfterSeq    int64          `json:"afterSeq"`
	ToSeq       int64          `json:"toSeq"`
	Observed    int            `json:"observed"`
	Retained    int            `json:"retained"`
	Limit       int            `json:"limit"`
	Summary     map[string]any `json:"summary,omitempty"`
}

func (Frame) Columns

func (Frame) Columns() []api.ColumnDef

func (Frame) Pretty

func (f Frame) Pretty() api.Text

func (Frame) PrettyFull

func (f Frame) PrettyFull() api.Textable

func (Frame) Row

func (f Frame) Row() map[string]any

func (Frame) RowDetail

func (f Frame) RowDetail() api.Textable

type Hierarchy

type Hierarchy struct {
	Metric string        `json:"metric"`
	Unit   string        `json:"unit"`
	Root   *WeightedNode `json:"root"`
}

type WeightedNode

type WeightedNode struct {
	ID    string  `json:"id"`
	Label string  `json:"label"`
	Self  float64 `json:"self"`
	Total float64 `json:"total"`

	Children []*WeightedNode `json:"children"`
}

func BuildHierarchy

func BuildHierarchy(stacks []WeightedStack) (*WeightedNode, error)

BuildHierarchy accepts root-first stacks with exclusive leaf weights.

type WeightedStack

type WeightedStack struct {
	Frames []string
	IDs    []string
	Value  float64
}

type Writer

type Writer struct {
	Backend Backend
	Schema  recordstore.KindSchema
	Stream  string
	// contains filtered or unexported fields
}

func (*Writer) Append

func (w *Writer) Append(ctx context.Context, frame Frame, rows []recordstore.Row) (Frame, error)

func (*Writer) Close

func (w *Writer) Close(ctx context.Context) error

Close seals completion metadata after the final checkpoint has been flushed.

Jump to

Keyboard shortcuts

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